kibi-cli 2.4.0 → 2.5.1

package/dist/utils/rule-registry.generated.js

@@ -38,6 +38,12 @@ export const GENERATED_RULES = [
         enforcementClass: "canonical",
         category: "integrity",
     },
+    {
+        name: "source-path-dangling",
+        description: "An authored entity's source field must name an existing workspace path (a #anchor suffix is ignored), an existing entity id, or an http(s) URL; a missing source is allowed",
+        enforcementClass: "canonical",
+        category: "integrity",
+    },
     {
         name: "no-cycles",
         description: "No circular dependency chains in requirements",
@@ -56,6 +62,42 @@ export const GENERATED_RULES = [
         enforcementClass: "canonical",
         category: "lifecycle",
     },
+    {
+        name: "superseded-requirement-open",
+        description: "A requirement that another requirement supersedes must have status closed, and supersedes links between requirements must not form a cycle",
+        enforcementClass: "canonical",
+        category: "lifecycle",
+    },
+    {
+        name: "scenario-feasibility",
+        description: "A scenario that expects success must not assume property values that cannot hold, alone or together, with what current requirements require through typed property values or rules, unless an approved exception requirement waives that requirement or the listed clauses",
+        enforcementClass: "canonical",
+        category: "integrity",
+    },
+    {
+        name: "scenario-feasibility-unknown",
+        description: "Advisory: a scenario that expects success assumes nothing, assumes values that contradict each other, assumes a property value no governing requirement constrains comparably (type, unit or operator mismatch, or conflicting requirements), leaves a governing rule's conditions undecided, or conflicts only with constraints whose validity window may not cover it, so its feasibility cannot be decided",
+        enforcementClass: "advisory",
+        category: "integrity",
+    },
+    {
+        name: "exception-claim-keys",
+        description: "An exception requirement's exempts_claims must name claim keys of a requirement it exempts, and requires an exempts link",
+        enforcementClass: "canonical",
+        category: "integrity",
+    },
+    {
+        name: "numeric-string-value",
+        description: "Advisory: a property value stores a numeric-looking string where the comparison is numeric (ordering operator, or an int/number fact on the same property); the finding names the fact and the typed value, without converting it",
+        enforcementClass: "advisory",
+        category: "integrity",
+    },
+    {
+        name: "rule-key-arguments-missing",
+        description: "Advisory: an opposing rule pair stays unresolved only because a body predicate declares no key_arguments; the finding names the predicate and the key positions that would decide the pair",
+        enforcementClass: "advisory",
+        category: "integrity",
+    },
     {
         name: "domain-contradictions",
         description: "Detect contradictions between requirements constraining the same fact",
@@ -95,7 +137,7 @@ export const GENERATED_RULES = [
     {
         name: "strict-fact-shape",
         description: "Detect malformed strict facts (facts with fact_kind that are missing required fields)",
-        enforcementClass: "advisory",
+        enforcementClass: "canonical",
         category: "integrity",
     },
     {
@@ -149,13 +191,13 @@ export const GENERATED_RULES = [
     },
     {
         name: "subject-key-identity",
-        description: "Subject keys must name a shared component, not be derived from a requirement ID",
+        description: "Subject keys must name a shared component, not be derived from a requirement ID, and one subject or claim must not be minted as several active subject facts or identical property_value facts",
         enforcementClass: "advisory",
         category: "integrity",
     },
     {
         name: "subject-key-shape",
-        description: "Subject keys follow dotted component.aspect[.sub] with lowercase snake segments",
+        description: "Subject keys follow dotted component.aspect[.sub] with lowercase snake segments, and property keys name a property rather than a numbered clause (clause_NN)",
         enforcementClass: "advisory",
         category: "integrity",
     },
@@ -166,6 +208,50 @@ export const GENERATED_RULES = [
         category: "integrity",
         diagnosticSeverity: "info",
     },
+    {
+        name: "exception-unapproved",
+        description: "Advisory: a current exception requirement exempts another requirement but has no approved_by, so it exempts nothing until a human approves it",
+        enforcementClass: "advisory",
+        category: "integrity",
+    },
+    {
+        name: "exception-approval-self-attested",
+        description: "Advisory: an agent-authored exception records approved_by but no human corroborated it (origin.approved_by or approval_ref is missing), so a human should confirm the approval",
+        enforcementClass: "advisory",
+        category: "integrity",
+    },
+    {
+        name: "agent-requirement-unapproved",
+        description: "Informational: current requirements authored by an agent (origin.kind agent) that no human has approved (origin.approved_by), listed up to 25 per check",
+        enforcementClass: "advisory",
+        category: "lifecycle",
+        diagnosticSeverity: "info",
+    },
+    {
+        name: "requirement-rationale-missing",
+        description: "Advisory: a current requirement authored by a human or an agent (origin.kind human or agent) states no rationale: no rationale field, no Rationale or Why section in its body, and no link to an ADR; listed up to 25 per check plus one summary finding",
+        enforcementClass: "advisory",
+        category: "lifecycle",
+    },
+    {
+        name: "symbol-owner-superseded",
+        description: "Advisory: a symbol whose every implements target is superseded or deprecated has no current owning requirement; listed up to 25 per check plus one summary finding",
+        enforcementClass: "advisory",
+        category: "traceability",
+    },
+    {
+        name: "adr-unlinked",
+        description: "Advisory: an accepted ADR that no requirement or other ADR is linked with (relates_to, supersedes or any typed edge, in either direction)",
+        enforcementClass: "advisory",
+        category: "lifecycle",
+    },
+    {
+        name: "adr-proposed",
+        description: "Informational: an ADR that is still proposed and not superseded, so nobody accepted or withdrew the decision",
+        enforcementClass: "advisory",
+        category: "lifecycle",
+        diagnosticSeverity: "info",
+    },
     {
         name: "predicate-schema-conformance",
         description: "Predicate facts match a predicate_schema (project-local, or the built-in catalog in the default namespace) and use its declared argument constants",

package/dist/utils/schema-version.d.ts

@@ -1,4 +1,4 @@
-export declare const LATEST_KB_SCHEMA_VERSION = 5;
+export declare const LATEST_KB_SCHEMA_VERSION = 7;
 export interface SchemaVersionStatus {
     status: "missing" | "invalid" | "older" | "current" | "newer";
     currentVersion: number | null;

package/dist/utils/schema-version.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema-version.d.ts","sourceRoot":"","sources":["../../src/utils/schema-version.ts"],"names":[],"mappings":"AAmBA,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAE1C,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,GAAG,OAAO,CAAC;IAC9D,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,OAAO,CAAC;IACxB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,MAAM,MAAM,mBAAmB,GAC3B;IAAE,aAAa,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAA;CAAE,GACrD,IAAI,GACJ,SAAS,CAAC;AAGd,wBAAgB,sBAAsB,CACpC,aAAa,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,GAChD,MAAM,GAAG,IAAI,CAgBf;AAGD,wBAAgB,sBAAsB,CACpC,MAAM,CAAC,EAAE,mBAAmB,GAC3B,mBAAmB,CAgDrB"}
+{"version":3,"file":"schema-version.d.ts","sourceRoot":"","sources":["../../src/utils/schema-version.ts"],"names":[],"mappings":"AAoBA,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAE1C,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,GAAG,OAAO,CAAC;IAC9D,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,OAAO,CAAC;IACxB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,MAAM,MAAM,mBAAmB,GAC3B;IAAE,aAAa,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAA;CAAE,GACrD,IAAI,GACJ,SAAS,CAAC;AAGd,wBAAgB,sBAAsB,CACpC,aAAa,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,GAChD,MAAM,GAAG,IAAI,CAgBf;AAGD,wBAAgB,sBAAsB,CACpC,MAAM,CAAC,EAAE,mBAAmB,GAC3B,mBAAmB,CAgDrB"}

package/dist/utils/schema-version.js

@@ -16,7 +16,8 @@
  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 // implements REQ-003
-export const LATEST_KB_SCHEMA_VERSION = 5;
+// Schema 7 requires strict fact shapes and encodes legacy polarity values.
+export const LATEST_KB_SCHEMA_VERSION = 7;
 // implements REQ-003
 export function normalizeSchemaVersion(schemaVersion) {
     if (schemaVersion === undefined || schemaVersion === null) {
@@ -47,7 +48,7 @@ export function getSchemaVersionStatus(config) {
             latestVersion,
             needsMigration: true,
             warning: hasSchemaVersion
-                ? "KB schemaVersion is invalid and should be migrated."
+                ? "KB schemaVersion is invalid; run 'kibi migrate' to plan the repair."
                 : "KB schemaVersion is missing; the repository should be initialized or migrated.",
         };
     }
@@ -66,7 +67,7 @@ export function getSchemaVersionStatus(config) {
             currentVersion,
             latestVersion,
             needsMigration: true,
-            warning: `KB schemaVersion ${currentVersion} is older than the latest version ${latestVersion} and should be migrated.`,
+            warning: `KB schemaVersion ${currentVersion} is older than the latest version ${latestVersion}; run 'kibi migrate' to plan the upgrade.`,
         };
     }
     return {

package/dist/utils/strict-modeling.d.ts

@@ -4,7 +4,7 @@ export interface SemanticClaim {
     source: string;
     subjectKey: string;
     propertyKey: string;
-    operator: "eq" | "gte" | "lte" | "neq" | "bool" | "polarity";
+    operator: "eq" | "gt" | "gte" | "lt" | "lte" | "neq" | "bool" | "polarity";
     value: string | number | boolean;
     confidence: number;
     provenance?: string;

package/dist/utils/strict-modeling.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"strict-modeling.d.ts","sourceRoot":"","sources":["../../src/utils/strict-modeling.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"strict-modeling.d.ts","sourceRoot":"","sources":["../../src/utils/strict-modeling.ts"],"names":[],"mappings":"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"}

package/dist/utils/strict-modeling.js

@@ -277,7 +277,7 @@ function buildUniqueTags(tags) {
 function buildPropertyFactTitle(normalizedPropertyKey, claim) {
     const label = humanizeKey(normalizedPropertyKey);
     if (claim.operator === "polarity") {
-        return `${label} ${normalizePolarityValue(claim.value)}`;
+        return `${label} ${normalizePolarityValue(claim.value) === "forbid" ? "forbidden" : "required"}`;
     }
     const operatorLabel = claim.operator === "bool"
         ? "="
@@ -287,12 +287,19 @@ function buildPropertyFactTitle(normalizedPropertyKey, claim) {
                 ? "!="
                 : claim.operator === "gte"
                     ? ">="
-                    : "<=";
+                    : claim.operator === "gt"
+                        ? ">"
+                        : claim.operator === "lt"
+                            ? "<"
+                            : "<=";
     return `${label} ${operatorLabel} ${String(claim.value)}`;
 }
 function buildPropertyFactFields(claim) {
     if (claim.operator === "polarity") {
         return {
+            operator: "eq",
+            value_type: "bool",
+            value_bool: true,
             polarity: normalizePolarityValue(claim.value),
         };
     }
@@ -305,9 +312,22 @@ function buildPropertyFactFields(claim) {
     }
     return {
         operator: claim.operator,
-        ...buildTypedValueFields(claim.value),
+        ...buildTypedValueFields(numericClaimValue(claim)),
     };
 }
+const ORDERING_OPERATORS = new Set(["gt", "gte", "lt", "lte"]);
+// implements REQ-kibi-truthful-consistency
+// An ordering comparison is numeric by definition, so a numeric string value
+// ("0", "2.5") is stored as int/number. Stored as a string it would be
+// invisible to numeric contradiction checks.
+function numericClaimValue(claim) {
+    if (typeof claim.value === "string" &&
+        ORDERING_OPERATORS.has(claim.operator) &&
+        /^\s*-?\d+(?:\.\d+)?\s*$/.test(claim.value)) {
+        return Number(claim.value);
+    }
+    return claim.value;
+}
 function buildTypedValueFields(value) {
     if (typeof value === "boolean") {
         return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-cli",
-  "version": "2.4.0",
+  "version": "2.5.1",
   "type": "module",
   "description": "Kibi CLI for knowledge base management",
   "engines": {
@@ -235,8 +235,8 @@
     "fast-glob": "^3.2.12",
     "gray-matter": "^4.0.3",
     "js-yaml": "^4.1.0",
-    "kibi-core": "^0.14.1",
-    "kibi-plugin-builtin": "^0.4.0",
+    "kibi-core": "^0.15.0",
+    "kibi-plugin-builtin": "^0.4.1",
     "kibi-plugin-sdk": "^0.4.0",
     "kibi-swipl": "^1.0.0",
     "saxes": "^6.0.0",

package/schema/entities.pl

@@ -30,6 +30,9 @@ entity_property(_, severity, atom).
 entity_property(_, links, list).
 entity_property(_, text_ref, uri).
 entity_property(_, sourceFile, uri).
+% Provenance of any authored entity: a JSON object (kind, ref, approved_by,
+% recorded_at) naming who authored it and on what authority.
+entity_property(_, origin, list_or_json).
 entity_property(req, semantic_text, string).
 entity_property(req, logic_claims, list).
 entity_property(req, semantic_clauses, list).
@@ -39,6 +42,17 @@ entity_property(req, semantic_source_hash, string).
 entity_property(req, semantic_inventory, list_or_json).
 entity_property(req, proof_exempt, boolean).
 entity_property(req, proof_exempt_reason, string).
+% Human approval of an exception requirement (one that `exempts` another).
+% Only an approved exception makes a success scenario feasible.
+entity_property(req, approved_by, string).
+entity_property(req, approval_ref, string).
+% Why the requirement exists, in the words of whoever stated the intent.
+% Explanation only: it is never part of the checked meaning.
+entity_property(req, rationale, string).
+% Claim keys of the exempted requirement an exception waives (all when absent).
+entity_property(req, exempts_claims, list).
+% Intended outcome of a scenario: success, rejection or error.
+entity_property(scenario, expects, atom).
 
 % Typed fact fields - only valid for fact entities
 entity_property(fact, fact_kind, atom).
@@ -65,6 +79,9 @@ entity_property(fact, predicate_arity, integer).
 entity_property(fact, argument_names, list).
 entity_property(fact, argument_types, list).
 entity_property(fact, argument_descriptions, list).
+% Predicate-schema functional dependency: the named arguments determine the
+% remaining ones, so two atoms with equal keys describe the same fact.
+entity_property(fact, key_arguments, list).
 % Predicate-schema vocabularies are JSON objects serialized as strings.
 entity_property(fact, argument_constants, string).
 entity_property(fact, argument_aliases, string).
@@ -112,6 +129,7 @@ optional_property(Type, priority) :- entity_type(Type).
 optional_property(Type, severity) :- entity_type(Type).
 optional_property(Type, links) :- entity_type(Type).
 optional_property(Type, text_ref) :- entity_type(Type).
+optional_property(Type, origin) :- entity_type(Type).
 optional_property(req, semantic_text).
 optional_property(req, logic_claims).
 optional_property(req, semantic_clauses).
@@ -121,6 +139,10 @@ optional_property(req, semantic_source_hash).
 optional_property(req, semantic_inventory).
 optional_property(req, proof_exempt).
 optional_property(req, proof_exempt_reason).
+optional_property(req, approved_by).
+optional_property(req, approval_ref).
+optional_property(req, rationale).
+optional_property(req, exempts_claims).
 optional_property(test, verification_scope).
 optional_property(test, verification_perspective).
 optional_property(test, proof_contract).

package/schema/relationships.pl

@@ -22,6 +22,8 @@ relationship_type(constrains).
 relationship_type(requires_property).
 relationship_type(requires_predicate).
 relationship_type(requires_rule).
+relationship_type(assumes).
+relationship_type(exempts).
 
 % valid_relationship(RelType, FromType, ToType).
 valid_relationship(depends_on, req, req).
@@ -45,6 +47,18 @@ valid_relationship(requires_property, req, fact).
 valid_relationship(requires_predicate, req, fact).
 valid_relationship(requires_rule, req, fact).
 
+%% assumes(+ScenarioId, +FactId)
+%% The scenario's outcome depends on the property_value fact holding (for
+%% example "the order total is 0"). Checked against current requirements by
+%% the scenario-feasibility rule.
+% implements REQ-kibi-scenario-feasibility-v2
+valid_relationship(assumes, scenario, fact).
+
+%% exempts(+ExceptionReqId, +BaseReqId)
+%% An approved exception requirement exempts the scenarios it specifies from
+%% BaseReqId's property constraints. BaseReqId stays current and unchanged.
+valid_relationship(exempts, req, req).
+
 %% supersedes(+NewAdrId, +OldAdrId)
 %% NewAdrId is the decision that replaces OldAdrId.
 %% OldAdrId's status should be archived or deprecated as a consequence.

package/schema/validation.pl

@@ -8,6 +8,7 @@
 
 :- use_module('entities.pl').
 :- use_module('relationships.pl').
+:- use_module(library(http/json)).
 
 % validate_entity(+Type, +Props:list)
 % Props is a list of Property=Value pairs (e.g. id=ID, title=Title)
@@ -19,7 +20,9 @@ validate_entity(Type, Props) :-
     % all properties have correct types
     forall(member(Key=Val, Props), validate_property_type(Type, Key, Val)),
     % validate entity-specific shape constraints
-    validate_entity_shape(Type, Props).
+    validate_entity_shape(Type, Props),
+    % provenance, when present, names a known origin kind
+    valid_origin_in_props(Props).
 
 % validate_relationship(+RelType, +From, +To)
 % From and To are pairs Type=Id or structures type(Type) - allow Type or Type=Id
@@ -105,6 +108,7 @@ is_fact_only_field(predicate_arity).
 is_fact_only_field(argument_names).
 is_fact_only_field(argument_types).
 is_fact_only_field(argument_descriptions).
+is_fact_only_field(key_arguments).
 is_fact_only_field(argument_constants).
 is_fact_only_field(argument_aliases).
 is_fact_only_field(aliases).
@@ -156,6 +160,7 @@ validate_fact_shape(predicate_schema, Props) :-
     memberchk(argument_types=ArgumentTypes, Props),
     same_length(ArgumentNames, ArgumentTypes),
     length(ArgumentNames, Arity),
+    valid_key_arguments(Props, ArgumentNames),
     valid_optional_fact_enums(Props),
     valid_polarity_in_props(Props), !.
 validate_fact_shape(predicate, Props) :-
@@ -185,6 +190,24 @@ validate_fact_shape(Kind, _Props) :-
     \+ memberchk(Kind, [subject, property_value, observation, meta, predicate_schema, predicate, rule_schema, rule]),
     fail.
 
+% valid_key_arguments(+Props, +ArgumentNames)
+% Optional key_arguments must be a non-empty list of distinct declared
+% argument names.
+valid_key_arguments(Props, ArgumentNames) :-
+    (   memberchk(key_arguments=Keys, Props)
+    ->  is_list(Keys),
+        Keys \= [],
+        maplist(text_atom, ArgumentNames, NameAtoms),
+        maplist(text_atom, Keys, KeyAtoms),
+        sort(KeyAtoms, UniqueKeys),
+        same_length(KeyAtoms, UniqueKeys),
+        forall(member(Key, KeyAtoms), memberchk(Key, NameAtoms))
+    ;   true
+    ).
+
+text_atom(Value, Atom) :- atom(Value), !, Atom = Value.
+text_atom(Value, Atom) :- string(Value), atom_string(Atom, Value).
+
 % valid_operator(+Op)
 valid_operator(Op) :- memberchk(Op, [eq, neq, lt, lte, gt, gte]), !.
 
@@ -256,3 +279,24 @@ value_type_matches_field(string, Props) :- memberchk(value_string=_, Props), !.
 value_type_matches_field(int, Props) :- memberchk(value_int=_, Props), !.
 value_type_matches_field(number, Props) :- memberchk(value_number=_, Props), !.
 value_type_matches_field(bool, Props) :- memberchk(value_bool=_, Props), !.
+
+% valid_origin_in_props(+Props)
+% Entity provenance travels as a JSON object string (or a dict). When present
+% its kind must be human, agent, migration or import.
+valid_origin_in_props(Props) :-
+    (   memberchk(origin=Raw, Props)
+    ->  origin_kind(Raw, Kind),
+        memberchk(Kind, [human, agent, migration, import])
+    ;   true
+    ).
+
+origin_kind(Raw, Kind) :-
+    (   is_dict(Raw)
+    ->  Dict = Raw
+    ;   (atom(Raw) ; string(Raw)),
+        catch(atom_json_dict(Raw, Dict, []), _, fail),
+        is_dict(Dict)
+    ),
+    get_dict(kind, Dict, RawKind),
+    (atom(RawKind) ; string(RawKind)),
+    atom_string(Kind, RawKind).

package/src/public/branch-resolver.ts

@@ -1,2 +1,3 @@
 export * from "../utils/branch-resolver.js";
 export * from "../utils/branch-store-locator.js";
+export * from "../runtime/detached-snapshot.js";

package/src/public/entity-origin.ts

@@ -0,0 +1,175 @@
+/*
+ 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",
+] as const;
+
+// implements REQ-kibi-entity-origin
+export type EntityOriginKind = (typeof ENTITY_ORIGIN_KINDS)[number];
+
+// implements REQ-kibi-entity-origin
+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. */
+// 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,
+} as const;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function nonEmptyText(value: unknown): string | undefined {
+  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: unknown,
+): { origin: EntityOrigin } | { error: string } {
+  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 as readonly string[]).includes(kind)
+  ) {
+    return {
+      error: `origin.kind must be one of ${ENTITY_ORIGIN_KINDS.join(", ")}`,
+    };
+  }
+  const origin: EntityOrigin = { kind: kind as EntityOriginKind };
+  for (const field of ["ref", "approved_by"] as const) {
+    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: unknown): EntityOrigin | null {
+  let candidate = value;
+  if (typeof candidate === "string") {
+    try {
+      candidate = JSON.parse(candidate) as unknown;
+    } catch {
+      return null;
+    }
+  }
+  const normalized = normalizeEntityOrigin(candidate);
+  return "origin" in normalized ? normalized.origin : null;
+}

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

@@ -293,6 +293,7 @@ function toExtractedEntity(entity: Record<string, unknown>): ExtractedEntity {
     "argument_names",
     "argument_types",
     "argument_descriptions",
+    "key_arguments",
     "aliases",
     "examples",
     "predicate_args",

package/src/public/impact/requirement-quality.ts

@@ -242,7 +242,7 @@ function createLogicalCoverageDiagnostics(
         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.",
+          "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/src/public/operations/catalog.ts

@@ -5,6 +5,7 @@ import {
 } from "./contracts.js";
 import { planBootstrapSpec } from "./specs/bootstrap.js";
 import { checkSpec } from "./specs/check.js";
+import { modelSpec, skillsSpec } from "./specs/composite.js";
 import { querySpec, searchSpec, statusSpec } from "./specs/discovery.js";
 import { prepareImpactReviewSpec } from "./specs/impact-review-preparation.js";
 import {
@@ -36,6 +37,7 @@ export const OPERATION_CATALOG = [
   skillsListSpec,
   skillsLoadSpec,
   skillsReadSpec,
+  skillsSpec,
   querySpec,
   searchSpec,
   statusSpec,
@@ -45,6 +47,7 @@ export const OPERATION_CATALOG = [
   semanticAdvisorSpec,
   modelRequirementSpec,
   suggestPredicatesSpec,
+  modelSpec,
   planBootstrapSpec,
   validateUpsertSpec,
   upsertSpec,