kibi-cli 2.3.0 → 2.5.0

package/dist/public/entity-origin.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Entity provenance (`origin`): who authored an entity and on what authority.
+ *
+ * `origin` is one structured property shared by every authored entity type.
+ * It is a YAML mapping in Markdown frontmatter and symbol manifests, a JSON
+ * object at the public operation boundary, and a JSON string inside Prolog
+ * (like `proof_contract`).
+ */
+/** How an entity entered the knowledge base. */
+export declare const ENTITY_ORIGIN_KINDS: readonly ["human", "agent", "migration", "import"];
+export type EntityOriginKind = (typeof ENTITY_ORIGIN_KINDS)[number];
+export type EntityOrigin = {
+    /** human | agent | migration | import */
+    kind: EntityOriginKind;
+    /** Source reference: URL, document path, ticket, commit or conversation id. */
+    ref?: string;
+    /** The person who approved the authored content. */
+    approved_by?: string;
+    /** ISO-8601 time the provenance was recorded. */
+    recorded_at?: string;
+};
+/** `ref` recorded on entities backfilled by the schema v5 -> v6 migration. */
+export declare const SCHEMA6_MIGRATION_ORIGIN_REF = "kibi migrate v5->v6";
+/** JSON Schema shared by the entity schema and the kb_upsert input schema. */
+export declare const ENTITY_ORIGIN_SCHEMA: {
+    readonly type: "object";
+    readonly required: readonly ["kind"];
+    readonly properties: {
+        readonly kind: {
+            readonly type: "string";
+            readonly enum: readonly ["human", "agent", "migration", "import"];
+            readonly description: "Who authored the entity: human, agent, migration (backfilled by kibi migrate) or import.";
+        };
+        readonly ref: {
+            readonly type: "string";
+            readonly minLength: 1;
+            readonly pattern: "\\S";
+            readonly description: "Source reference for the authored content: URL, document path, ticket, commit or conversation id.";
+        };
+        readonly approved_by: {
+            readonly type: "string";
+            readonly minLength: 1;
+            readonly pattern: "\\S";
+            readonly description: "The person who reviewed and approved this entity's content. Distinct from the requirement-level approved_by of an exception.";
+        };
+        readonly recorded_at: {
+            readonly type: "string";
+            readonly pattern: "^\\d{4}-\\d{2}-\\d{2}(?:[T ]\\d{2}:\\d{2}(?::\\d{2}(?:\\.\\d+)?)?(?:Z|[+-]\\d{2}:?\\d{2})?)?$";
+            readonly description: "ISO-8601 time the provenance was recorded.";
+        };
+    };
+    readonly additionalProperties: false;
+};
+/**
+ * Normalize an authored origin mapping. YAML parsers turn an unquoted
+ * `recorded_at` into a Date; it is stored as its ISO-8601 string. Returns the
+ * reason when the mapping is not a valid origin.
+ */
+export declare function normalizeEntityOrigin(value: unknown): {
+    origin: EntityOrigin;
+} | {
+    error: string;
+};
+/**
+ * Read an origin from a compiled entity row: an object at the public
+ * boundary, or the JSON string Prolog stores. Malformed values read as absent.
+ */
+export declare function readEntityOrigin(value: unknown): EntityOrigin | null;
+//# sourceMappingURL=entity-origin.d.ts.map

package/dist/public/entity-origin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-origin.d.ts","sourceRoot":"","sources":["../../src/public/entity-origin.ts"],"names":[],"mappings":"AAkBA;;;;;;;GAOG;AAEH,gDAAgD;AAEhD,eAAO,MAAM,mBAAmB,oDAKtB,CAAC;AAGX,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAGpE,MAAM,MAAM,YAAY,GAAG;IACzB,yCAAyC;IACzC,IAAI,EAAE,gBAAgB,CAAC;IACvB,+EAA+E;IAC/E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,oDAAoD;IACpD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iDAAiD;IACjD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,8EAA8E;AAE9E,eAAO,MAAM,4BAA4B,wBAAwB,CAAC;AAKlE,8EAA8E;AAE9E,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+BvB,CAAC;AAYX;;;;GAIG;AAEH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,OAAO,GACb;IAAE,MAAM,EAAE,YAAY,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CA6C9C;AAED;;;GAGG;AAEH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,YAAY,GAAG,IAAI,CAWpE"}

package/dist/public/entity-origin.js

@@ -0,0 +1,142 @@
+/*
+ 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/>.
+*/
+/**
+ * Entity provenance (`origin`): who authored an entity and on what authority.
+ *
+ * `origin` is one structured property shared by every authored entity type.
+ * It is a YAML mapping in Markdown frontmatter and symbol manifests, a JSON
+ * object at the public operation boundary, and a JSON string inside Prolog
+ * (like `proof_contract`).
+ */
+/** How an entity entered the knowledge base. */
+// implements REQ-kibi-entity-origin
+export const ENTITY_ORIGIN_KINDS = [
+    "human",
+    "agent",
+    "migration",
+    "import",
+];
+/** `ref` recorded on entities backfilled by the schema v5 -> v6 migration. */
+// implements REQ-kibi-entity-origin
+export const SCHEMA6_MIGRATION_ORIGIN_REF = "kibi migrate v5->v6";
+const ISO_TIMESTAMP_PATTERN = "^\\d{4}-\\d{2}-\\d{2}(?:[T ]\\d{2}:\\d{2}(?::\\d{2}(?:\\.\\d+)?)?(?:Z|[+-]\\d{2}:?\\d{2})?)?$";
+/** JSON Schema shared by the entity schema and the kb_upsert input schema. */
+// implements REQ-kibi-entity-origin
+export const ENTITY_ORIGIN_SCHEMA = {
+    type: "object",
+    required: ["kind"],
+    properties: {
+        kind: {
+            type: "string",
+            enum: [...ENTITY_ORIGIN_KINDS],
+            description: "Who authored the entity: human, agent, migration (backfilled by kibi migrate) or import.",
+        },
+        ref: {
+            type: "string",
+            minLength: 1,
+            pattern: "\\S",
+            description: "Source reference for the authored content: URL, document path, ticket, commit or conversation id.",
+        },
+        approved_by: {
+            type: "string",
+            minLength: 1,
+            pattern: "\\S",
+            description: "The person who reviewed and approved this entity's content. Distinct from the requirement-level approved_by of an exception.",
+        },
+        recorded_at: {
+            type: "string",
+            pattern: ISO_TIMESTAMP_PATTERN,
+            description: "ISO-8601 time the provenance was recorded.",
+        },
+    },
+    additionalProperties: false,
+};
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function nonEmptyText(value) {
+    return typeof value === "string" && value.trim() !== ""
+        ? value.trim()
+        : undefined;
+}
+/**
+ * Normalize an authored origin mapping. YAML parsers turn an unquoted
+ * `recorded_at` into a Date; it is stored as its ISO-8601 string. Returns the
+ * reason when the mapping is not a valid origin.
+ */
+// implements REQ-kibi-entity-origin, REQ-007
+export function normalizeEntityOrigin(value) {
+    if (!isRecord(value)) {
+        return { error: "origin must be a mapping with at least a kind" };
+    }
+    const allowed = new Set(["kind", "ref", "approved_by", "recorded_at"]);
+    const unknown = Object.keys(value).filter((key) => !allowed.has(key));
+    if (unknown.length > 0) {
+        return {
+            error: `origin has unknown field(s) ${unknown.join(", ")}; allowed: kind, ref, approved_by, recorded_at`,
+        };
+    }
+    const kind = value.kind;
+    if (typeof kind !== "string" ||
+        !ENTITY_ORIGIN_KINDS.includes(kind)) {
+        return {
+            error: `origin.kind must be one of ${ENTITY_ORIGIN_KINDS.join(", ")}`,
+        };
+    }
+    const origin = { kind: kind };
+    for (const field of ["ref", "approved_by"]) {
+        if (value[field] === undefined)
+            continue;
+        const text = nonEmptyText(value[field]);
+        if (text === undefined) {
+            return { error: `origin.${field} must be a non-empty string` };
+        }
+        origin[field] = text;
+    }
+    if (value.recorded_at !== undefined) {
+        const recordedAt = value.recorded_at instanceof Date
+            ? Number.isNaN(value.recorded_at.getTime())
+                ? undefined
+                : value.recorded_at.toISOString()
+            : nonEmptyText(value.recorded_at);
+        if (recordedAt === undefined ||
+            !new RegExp(ISO_TIMESTAMP_PATTERN).test(recordedAt)) {
+            return { error: "origin.recorded_at must be an ISO-8601 timestamp" };
+        }
+        origin.recorded_at = recordedAt;
+    }
+    return { origin };
+}
+/**
+ * Read an origin from a compiled entity row: an object at the public
+ * boundary, or the JSON string Prolog stores. Malformed values read as absent.
+ */
+// implements REQ-kibi-entity-origin
+export function readEntityOrigin(value) {
+    let candidate = value;
+    if (typeof candidate === "string") {
+        try {
+            candidate = JSON.parse(candidate);
+        }
+        catch {
+            return null;
+        }
+    }
+    const normalized = normalizeEntityOrigin(candidate);
+    return "origin" in normalized ? normalized.origin : null;
+}

package/dist/public/impact/full-kb-quality.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"full-kb-quality.d.ts","sourceRoot":"","sources":["../../../src/public/impact/full-kb-quality.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAEV,gBAAgB,EACjB,MAAM,8BAA8B,CAAC;AAatC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAC;AAWjE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AASpD,KAAK,+BAA+B,GAAG;IACrC,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,OAAO,GAAG,eAAe,CAAC,CAAC;IAC7D,QAAQ,CAAC,sBAAsB,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACtD,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B,CAAC;AAmgBF,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,OAAO,GAAG,eAAe,CAAC,GAClD,OAAO,CAAC,gBAAgB,EAAE,CAAC,CA8C7B;AAED,wBAAgB,eAAe,CAC7B,UAAU,EAAE,OAAO,GAClB,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,CAM/C;AA2ID,wBAAsB,+BAA+B,CACnD,OAAO,EAAE,+BAA+B,GACvC,OAAO,CAAC,SAAS,iBAAiB,EAAE,CAAC,CAkCvC"}
+{"version":3,"file":"full-kb-quality.d.ts","sourceRoot":"","sources":["../../../src/public/impact/full-kb-quality.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAEV,gBAAgB,EACjB,MAAM,8BAA8B,CAAC;AAatC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAC;AAWjE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AASpD,KAAK,+BAA+B,GAAG;IACrC,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,OAAO,GAAG,eAAe,CAAC,CAAC;IAC7D,QAAQ,CAAC,sBAAsB,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACtD,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B,CAAC;AAogBF,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,OAAO,GAAG,eAAe,CAAC,GAClD,OAAO,CAAC,gBAAgB,EAAE,CAAC,CA8C7B;AAED,wBAAgB,eAAe,CAC7B,UAAU,EAAE,OAAO,GAClB,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,CAM/C;AA2ID,wBAAsB,+BAA+B,CACnD,OAAO,EAAE,+BAA+B,GACvC,OAAO,CAAC,SAAS,iBAAiB,EAAE,CAAC,CAkCvC"}

package/dist/public/impact/full-kb-quality.js

@@ -221,6 +221,7 @@ function toExtractedEntity(entity) {
         "argument_names",
         "argument_types",
         "argument_descriptions",
+        "key_arguments",
         "aliases",
         "examples",
         "predicate_args",

package/dist/public/impact/requirement-quality.js

@@ -182,7 +182,7 @@ function createLogicalCoverageDiagnostics(options) {
                 files: [result.entity.source],
                 docs: ["docs/modeling-cheatsheet.md", "docs/error-reference.md"],
                 message: `Current requirement ${result.entity.id} has no atomic logic_claims manifest, so prose and existing fact links cannot prove complete logical coverage.`,
-                suggestion: "Call kb_semantic_advisor with the complete requirement prose and atomic clauses, ground each returned claim key through kb_model_requirement or kb_suggest_predicates, and persist all keys in logic_claims.",
+                suggestion: "Call kb_model with mode analyze on the complete requirement prose and atomic clauses, ground each returned claim key through kb_model (mode requirement or predicates), and persist all keys in logic_claims.",
                 evidence: {
                     strictRelationshipTypes: relationshipTypes,
                 },

package/dist/public/operations/catalog.d.ts

@@ -58,6 +58,24 @@ export declare const OPERATION_CATALOG: readonly [{
     readonly execute: (input: Readonly<Record<string, unknown>>, _context: import("./runtime-types.js").OperationContext) => Promise<import("./types.js").OperationResult<{
         readonly content: string;
     }>>;
+}, {
+    readonly name: "kb_skills";
+    readonly cliName: "skill";
+    readonly 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.";
+    readonly businessInputSchema: {
+        readonly type: "object";
+        readonly required: readonly ["action"];
+        readonly properties: {
+            readonly action: {
+                readonly type: "string";
+                readonly enum: readonly ["list", "load", "read"];
+                readonly description: "list, load (needs id) or read (needs id and resource).";
+            };
+        };
+    };
+    readonly requiresProlog: false;
+    readonly effects: readonly ["local-read"];
+    readonly execute: (input: Readonly<Record<string, unknown>>, context: import("./runtime-types.js").OperationContext) => Promise<import("./types.js").OperationResult<Record<string, unknown>>>;
 }, {
     readonly name: "kb_query";
     readonly cliName: "query";
@@ -104,7 +122,7 @@ export declare const OPERATION_CATALOG: readonly [{
 }, {
     readonly name: "kb_search";
     readonly cliName: "search";
-    readonly 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.";
+    readonly description: "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.";
     readonly businessInputSchema: {
         readonly type: "object";
         readonly required: readonly ["query"];
@@ -135,8 +153,13 @@ export declare const OPERATION_CATALOG: readonly [{
             readonly rankingMode: {
                 readonly type: "string";
                 readonly enum: readonly ["legacy", "intent-v1"];
-                readonly default: "legacy";
-                readonly description: "Optional deterministic ranking mode. Omit for backward-compatible lexical search; use intent-v1 for semantic facets, source-aware evidence, graph boosts, and abstention.";
+                readonly default: "intent-v1";
+                readonly description: "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.";
+            };
+            readonly answer: {
+                readonly type: "boolean";
+                readonly default: true;
+                readonly 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.";
             };
             readonly semanticFacets: {
                 readonly type: "object";
@@ -528,8 +551,8 @@ export declare const OPERATION_CATALOG: readonly [{
             };
             readonly operator: {
                 readonly type: "string";
-                readonly enum: readonly ["eq", "gte", "lte", "neq", "bool", "polarity"];
-                readonly description: "Optional extracted semantic claim operator. Example: 'eq'.";
+                readonly enum: readonly ["eq", "gt", "gte", "lt", "lte", "neq", "bool", "polarity"];
+                readonly description: "Optional extracted semantic claim operator. Use gt/lt for strict bounds ('greater than zero' is gt 0, not gte 0). Example: 'eq'.";
             };
             readonly value: {
                 readonly description: "Optional extracted semantic claim value. Accepts string, number, or boolean.";
@@ -643,10 +666,28 @@ export declare const OPERATION_CATALOG: readonly [{
     readonly requiresProlog: true;
     readonly effects: readonly ["kb-read"];
     readonly execute: typeof import("../../operations/modeling/suggest-predicates.js").executeSuggestPredicates;
+}, {
+    readonly name: "kb_model";
+    readonly cliName: "model";
+    readonly 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.";
+    readonly businessInputSchema: {
+        readonly type: "object";
+        readonly required: readonly ["mode", "text"];
+        readonly properties: {
+            readonly mode: {
+                readonly type: "string";
+                readonly enum: readonly ["analyze", "requirement", "predicates"];
+                readonly description: "analyze (advisor receipt), requirement (strict claim write set) or predicates (ontology predicate plan).";
+            };
+        };
+    };
+    readonly requiresProlog: true;
+    readonly effects: readonly ["kb-read"];
+    readonly execute: (input: Readonly<Record<string, unknown>>, context: import("./runtime-types.js").OperationContext) => Promise<import("./types.js").OperationResult<Record<string, unknown>>>;
 }, {
     readonly name: "kb_plan_bootstrap";
     readonly cliName: "plan-bootstrap";
-    readonly 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.";
+    readonly description: "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.";
     readonly businessInputSchema: {
         readonly type: "object";
         readonly properties: {
@@ -713,6 +754,78 @@ export declare const OPERATION_CATALOG: readonly [{
                         };
                         readonly description: "Optional verification commands, documents, or checkpoints to reference in the output.";
                     };
+                    readonly knowledgeSources: {
+                        readonly type: "array";
+                        readonly maxItems: 50;
+                        readonly 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.";
+                        readonly items: {
+                            readonly type: "object";
+                            readonly required: readonly ["id", "kind", "title", "locator", "authority"];
+                            readonly additionalProperties: false;
+                            readonly properties: {
+                                readonly id: {
+                                    readonly type: "string";
+                                    readonly pattern: "^[a-z0-9][a-z0-9-]*$";
+                                    readonly description: "Stable kebab-case handle that intentClaims cite, for example jira-payments.";
+                                };
+                                readonly kind: {
+                                    readonly type: "string";
+                                    readonly enum: readonly ["issue_tracker", "wiki", "specification", "design", "decision_log", "support", "chat", "repository_docs", "other"];
+                                };
+                                readonly title: {
+                                    readonly type: "string";
+                                    readonly minLength: 1;
+                                };
+                                readonly locator: {
+                                    readonly type: "string";
+                                    readonly minLength: 1;
+                                    readonly description: "Where the source lives: a URL, project key, space name, or repo-relative path.";
+                                };
+                                readonly authority: {
+                                    readonly type: "string";
+                                    readonly enum: readonly ["authoritative", "supporting", "stale"];
+                                    readonly description: "The human's call: authoritative claims become higher-confidence candidates, supporting claims lower ones, and stale sources are cited but never produce candidates.";
+                                };
+                                readonly connector: {
+                                    readonly type: "string";
+                                    readonly description: "Optional name of the MCP server or tool the agent used to read the source.";
+                                };
+                                readonly notes: {
+                                    readonly type: "string";
+                                };
+                            };
+                        };
+                    };
+                    readonly intentClaims: {
+                        readonly type: "array";
+                        readonly maxItems: 200;
+                        readonly 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.";
+                        readonly items: {
+                            readonly type: "object";
+                            readonly required: readonly ["statement", "sourceId", "reference"];
+                            readonly additionalProperties: false;
+                            readonly properties: {
+                                readonly statement: {
+                                    readonly type: "string";
+                                    readonly minLength: 1;
+                                    readonly description: "One normative statement in the source's meaning, for example 'Refunds must not exceed the original charge.'";
+                                };
+                                readonly sourceId: {
+                                    readonly type: "string";
+                                    readonly description: "The id of a declared knowledge source.";
+                                };
+                                readonly reference: {
+                                    readonly type: "string";
+                                    readonly minLength: 1;
+                                    readonly description: "Exact citation inside the source: a ticket key, page URL, or section anchor.";
+                                };
+                                readonly excerpt: {
+                                    readonly type: "string";
+                                    readonly description: "Optional short quote supporting the claim.";
+                                };
+                            };
+                        };
+                    };
                 };
             };
         };
@@ -723,7 +836,7 @@ export declare const OPERATION_CATALOG: readonly [{
 }, {
     readonly name: "kb_validate_upsert";
     readonly cliName: "validate-upsert";
-    readonly 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.";
+    readonly 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 mode requirement or predicates, ambiguity review, or an ontology-gap observation.";
     readonly businessInputSchema: {
         readonly type: "object";
         readonly required: readonly ["type", "id", "properties"];
@@ -753,7 +866,7 @@ export declare const OPERATION_CATALOG: readonly [{
 }, {
     readonly name: "kb_upsert";
     readonly cliName: "upsert";
-    readonly 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.";
+    readonly description: "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.";
     readonly businessInputSchema: {
         readonly type: "object";
         readonly required: readonly ["type", "id", "properties"];
@@ -813,6 +926,36 @@ export declare const OPERATION_CATALOG: readonly [{
                         readonly type: "string";
                         readonly description: "Optional text anchor/reference. Example: 'requirements.md#L40'.";
                     };
+                    readonly origin: {
+                        readonly 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.";
+                        readonly type: "object";
+                        readonly required: readonly ["kind"];
+                        readonly properties: {
+                            readonly kind: {
+                                readonly type: "string";
+                                readonly enum: readonly ["human", "agent", "migration", "import"];
+                                readonly description: "Who authored the entity: human, agent, migration (backfilled by kibi migrate) or import.";
+                            };
+                            readonly ref: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                                readonly pattern: "\\S";
+                                readonly description: "Source reference for the authored content: URL, document path, ticket, commit or conversation id.";
+                            };
+                            readonly approved_by: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                                readonly pattern: "\\S";
+                                readonly description: "The person who reviewed and approved this entity's content. Distinct from the requirement-level approved_by of an exception.";
+                            };
+                            readonly recorded_at: {
+                                readonly type: "string";
+                                readonly pattern: "^\\d{4}-\\d{2}-\\d{2}(?:[T ]\\d{2}:\\d{2}(?::\\d{2}(?:\\.\\d+)?)?(?:Z|[+-]\\d{2}:?\\d{2})?)?$";
+                                readonly description: "ISO-8601 time the provenance was recorded.";
+                            };
+                        };
+                        readonly additionalProperties: false;
+                    };
                     readonly semantic_text: {
                         readonly type: "string";
                         readonly description: "Requirement-only authored prose used for semantic inventory hashes and UTF-8 spans. Keep text_ref available for independent document or code evidence.";
@@ -825,7 +968,7 @@ export declare const OPERATION_CATALOG: readonly [{
                             readonly type: "string";
                             readonly pattern: "^CLAIM-[A-F0-9]{16}$";
                         };
-                        readonly 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.";
+                        readonly description: "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.";
                     };
                     readonly semantic_clauses: {
                         readonly type: "array";
@@ -834,18 +977,43 @@ export declare const OPERATION_CATALOG: readonly [{
                             readonly type: "string";
                             readonly minLength: 1;
                         };
-                        readonly description: "Optional complete atomic decomposition used by kb_semantic_advisor and proposition-complete ingestion. Preserve it when automatic sentence splitting needs a reviewed override.";
+                        readonly description: "Optional complete atomic decomposition used by kb_model mode analyze and proposition-complete ingestion. Preserve it when automatic sentence splitting needs a reviewed override.";
                     };
                     readonly semantic_inventory_version: {
                         readonly type: "string";
                         readonly const: "kibi.semantic-inventory.v1";
-                        readonly description: "Requirement-only proposition ledger contract version returned by kb_semantic_advisor.";
+                        readonly description: "Requirement-only proposition ledger contract version returned by kb_model mode analyze (CLI: semantic-advisor).";
                     };
                     readonly semantic_source_field: {
                         readonly type: "string";
                         readonly enum: readonly ["semantic_text", "text_ref", "title"];
                         readonly description: "Requirement field whose exact UTF-8 bytes anchor semantic_inventory spans.";
                     };
+                    readonly approved_by: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                        readonly 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.";
+                    };
+                    readonly approval_ref: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                        readonly description: "Requirement-only. Optional reference to the exception's approval decision record.";
+                    };
+                    readonly rationale: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                        readonly description: "Requirement-only. Why the requirement exists, in one or two sentences from whoever stated the intent; not part of the checked meaning.";
+                    };
+                    readonly exempts_claims: {
+                        readonly type: "array";
+                        readonly minItems: 1;
+                        readonly uniqueItems: true;
+                        readonly items: {
+                            readonly type: "string";
+                            readonly pattern: "^CLAIM-[A-F0-9]{16}$";
+                        };
+                        readonly description: "Requirement-only. Claim keys of the exempted requirement whose constraints this exception waives; omit to waive the whole requirement.";
+                    };
                     readonly semantic_source_hash: {
                         readonly type: "string";
                         readonly pattern: "^[a-f0-9]{64}$";
@@ -1175,7 +1343,7 @@ export declare const OPERATION_CATALOG: readonly [{
                     readonly fact_kind: {
                         readonly type: "string";
                         readonly enum: readonly ["subject", "property_value", "observation", "meta", "predicate_schema", "predicate", "rule_schema", "rule"];
-                        readonly 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.";
+                        readonly 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 (mode requirement or predicates) when starting from prose.";
                     };
                     readonly subject_key: {
                         readonly type: "string";
@@ -1243,14 +1411,14 @@ export declare const OPERATION_CATALOG: readonly [{
                     };
                     readonly predicate_name: {
                         readonly type: "string";
-                        readonly description: "Optional predicate name for ontology predicate facts. Prefer kb_suggest_predicates before hand-writing predicate_name.";
+                        readonly description: "Optional predicate name for ontology predicate facts. Prefer kb_model mode predicates before hand-writing predicate_name.";
                     };
                     readonly predicate_args: {
                         readonly type: "array";
                         readonly items: {
                             readonly type: "string";
                         };
-                        readonly description: "Optional ordered predicate arguments for ontology predicate facts. Prefer kb_suggest_predicates before hand-writing predicate_args.";
+                        readonly description: "Optional ordered predicate arguments for ontology predicate facts. Prefer kb_model mode predicates before hand-writing predicate_args.";
                     };
                     readonly predicate_namespace: {
                         readonly type: "string";
@@ -1282,6 +1450,16 @@ export declare const OPERATION_CATALOG: readonly [{
                         };
                         readonly description: "Optional ordered argument explanations.";
                     };
+                    readonly key_arguments: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                            readonly minLength: 1;
+                        };
+                        readonly minItems: 1;
+                        readonly uniqueItems: true;
+                        readonly 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.";
+                    };
                     readonly argument_constants: {
                         readonly type: "object";
                         readonly additionalProperties: {
@@ -1321,7 +1499,7 @@ export declare const OPERATION_CATALOG: readonly [{
                     };
                     readonly semantic_inventory: {
                         readonly type: "array";
-                        readonly description: "Requirement proposition ledger returned by kb_semantic_advisor; preserve entries while modeling each assertive span.";
+                        readonly description: "Requirement proposition ledger returned by kb_model mode analyze (CLI: semantic-advisor); preserve entries while modeling each assertive span.";
                         readonly items: {
                             readonly type: "object";
                         };
@@ -1374,7 +1552,7 @@ export declare const OPERATION_CATALOG: readonly [{
                     readonly properties: {
                         readonly type: {
                             readonly type: "string";
-                            readonly enum: readonly ["depends_on", "specified_by", "verified_by", "validates", "implements", "covered_by", "executable_for", "constrained_by", "constrains", "requires_property", "requires_predicate", "requires_rule", "guards", "publishes", "consumes", "supersedes", "restates", "relates_to"];
+                            readonly enum: readonly ["depends_on", "specified_by", "verified_by", "validates", "implements", "covered_by", "executable_for", "constrained_by", "constrains", "requires_property", "requires_predicate", "requires_rule", "guards", "publishes", "consumes", "supersedes", "restates", "assumes", "exempts", "relates_to"];
                             readonly description: "Relationship type enum. Use only supported values. Direction semantics follow KB model (e.g., implements symbol->req, verified_by req/scenario->test, executable_for symbol->test).";
                         };
                         readonly from: {
@@ -1388,6 +1566,11 @@ export declare const OPERATION_CATALOG: readonly [{
                     };
                 };
             };
+            readonly dryRun: {
+                readonly type: "boolean";
+                readonly default: false;
+                readonly 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.";
+            };
             readonly document: {
                 readonly type: "object";
                 readonly additionalProperties: false;
@@ -1480,7 +1663,7 @@ export declare const OPERATION_CATALOG: readonly [{
                     readonly type: "string";
                     readonly enum: readonly string[];
                 };
-                readonly description: "Optional rule subset. 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. If omitted, server runs canonical and advisory rules plus the full-KB qualityDiagnostics audit scan, including usage telemetry acceptance when evidence exists; migration rules run only when explicitly selected. Advisory and migration findings are non-blocking qualityDiagnostics. If supplied, server preserves scoped validation and skips the full-KB advisory scan.";
+                readonly description: "Optional rule subset. Allowed: 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. If omitted, server runs canonical and advisory rules plus the full-KB qualityDiagnostics audit scan, including usage telemetry acceptance when evidence exists; migration rules run only when explicitly selected. Advisory and migration findings are non-blocking qualityDiagnostics. If supplied, server preserves scoped validation and skips the full-KB advisory scan.";
             };
             readonly sourceFiles: {
                 readonly type: "array";
@@ -1513,7 +1696,7 @@ export declare const OPERATION_CATALOG: readonly [{
             readonly async: {
                 readonly type: "boolean";
                 readonly default: false;
-                readonly 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.";
+                readonly 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. The MCP server registers kb_job_status only when KIBI_MCP_OPTIONAL_TOOLS includes it; otherwise async runs the check synchronously.";
             };
         };
     };
@@ -1811,7 +1994,7 @@ export declare const OPERATION_CATALOG: readonly [{
 }, {
     readonly name: "kb_apply_plan";
     readonly cliName: "apply-plan";
-    readonly 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.";
+    readonly 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. 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.";
     readonly businessInputSchema: {
         readonly type: "object";
         readonly oneOf: readonly [{
@@ -1851,7 +2034,7 @@ export declare const OPERATION_CATALOG: readonly [{
             readonly recoveryJournalId: {
                 readonly type: "string";
                 readonly pattern: "^[A-Za-z0-9._-]+$";
-                readonly description: "Typed recovery journal identifier returned by a committed_with_repairs result. Recovery replays only the immutable journal and never the original plan request.";
+                readonly description: "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.";
             };
         };
     };