kibi-cli 2.20.0 → 2.21.2

package/dist/relationships/shards.js

@@ -197,15 +197,21 @@ export function renderShardWithout(text, selectors, shardPath) {
     }
     return document.toString();
 }
-export function removeRelationshipsFromShards(kbRoot, selectors) {
+/**
+ * Render every shard that holds a selected relationship without writing it,
+ * so a dry run can report the exact bytes a delete would publish.
+ */
+// implements REQ-kibi-operation-interface-parity
+export function planRelationshipShardRemovals(kbRoot, selectors) {
     const wanted = new Set(selectors.map((selector) => `${selector.type}\0${selector.from}\0${selector.to}`));
     const removed = new Map();
+    const bodies = new Map();
     for (const shardPath of listShards(kbRoot)) {
         const records = readShard(shardPath);
         const matching = records.filter((record) => wanted.has(`${record.type}\0${record.from}\0${record.to}`));
         if (matching.length === 0)
             continue;
-        atomicWriteText(shardPath, renderShardWithout(fs.readFileSync(shardPath, "utf8"), selectors, shardPath));
+        bodies.set(shardPath, renderShardWithout(fs.readFileSync(shardPath, "utf8"), selectors, shardPath));
         for (const record of matching) {
             const key = `${record.type}\0${record.from}\0${record.to}`;
             const entry = removed.get(key) ?? { paths: [], sources: [] };
@@ -214,15 +220,25 @@ export function removeRelationshipsFromShards(kbRoot, selectors) {
             removed.set(key, entry);
         }
     }
-    return selectors.map((selector) => {
-        const entry = removed.get(`${selector.type}\0${selector.from}\0${selector.to}`);
-        return {
-            selector,
-            shardPaths: entry?.paths ?? [],
-            sources: entry?.sources ?? [],
-            removed: entry !== undefined,
-        };
-    });
+    return {
+        bodies,
+        removals: selectors.map((selector) => {
+            const entry = removed.get(`${selector.type}\0${selector.from}\0${selector.to}`);
+            return {
+                selector,
+                shardPaths: entry?.paths ?? [],
+                sources: entry?.sources ?? [],
+                removed: entry !== undefined,
+            };
+        }),
+    };
+}
+export function removeRelationshipsFromShards(kbRoot, selectors) {
+    const planned = planRelationshipShardRemovals(kbRoot, selectors);
+    for (const [shardPath, body] of planned.bodies) {
+        atomicWriteText(shardPath, body);
+    }
+    return planned.removals;
 }
 /**
  * Serializes records to YAML format.

package/dist/schemas/entity.schema.json

@@ -514,6 +514,15 @@
             },
             "additionalProperties": false
         },
+        "firmness": {
+            "type": "string",
+            "enum": [
+                "firm",
+                "default",
+                "exploratory"
+            ],
+            "description": "Requirement and ADR only. How firmly the decision was made. firm: a human stated it as a rule; it needs a ref (origin.ref, or approval_ref on a requirement) to their words, and only a human may change it. default (assumed when absent): a delegated or agent choice; a later agent may supersede it with evidence. exploratory: a flagged guess, expected to be revisited."
+        },
         "expects": {
             "type": "string",
             "enum": [
@@ -1657,6 +1666,25 @@
                 }
             }
         },
+        {
+            "if": {
+                "properties": {
+                    "type": {
+                        "enum": [
+                            "req",
+                            "adr"
+                        ]
+                    }
+                }
+            },
+            "else": {
+                "not": {
+                    "required": [
+                        "firmness"
+                    ]
+                }
+            }
+        },
         {
             "if": {
                 "properties": {
@@ -1675,35 +1703,12 @@
         },
         {
             "if": {
-                "anyOf": [
-                    {
-                        "required": [
-                            "claim_key"
-                        ]
-                    },
-                    {
-                        "required": [
-                            "claim_text"
-                        ],
-                        "not": {
-                            "properties": {
-                                "fact_kind": {
-                                    "enum": [
-                                        "observation",
-                                        "meta"
-                                    ]
-                                }
-                            },
-                            "required": [
-                                "fact_kind"
-                            ]
-                        }
-                    }
+                "required": [
+                    "claim_key"
                 ]
             },
             "then": {
                 "required": [
-                    "claim_key",
                     "claim_text"
                 ]
             }

package/dist/search-answer.d.ts

@@ -1,3 +1,4 @@
+import { type Firmness } from "./decision-firmness.js";
 import type { IntentSearchMatch } from "./intent-search.js";
 import type { PrologPort } from "./public/operations/runtime-types.js";
 /**
@@ -19,6 +20,12 @@ export type SearchAnswerEntity = Readonly<{
     id: string;
     title: string;
     status?: string;
+    /**
+     * Requirements and ADRs: how firmly the decision was made. `firm` (a human
+     * stated it; ask before changing), `default` (supersede it with evidence),
+     * `exploratory` (a guess to revisit).
+     */
+    firmness?: Firmness;
 }>;
 /**
  * A test verifying a governing requirement. `via` is `"direct"` for a test
@@ -69,8 +76,13 @@ export type SearchAnswerException = SearchAnswerEntity & Readonly<{
 /**
  * A linked fact says what it states in its typed form, so an agent can read
  * `has_role(alice, admin)` or `user.role_assignment max_roles lte 2` without
- * opening the entity, and `ask` is the exact kb_query that answers precise
- * questions about the same predicate or subject.
+ * opening the entity, and `ask` is the kb_query that reproduces the fact's
+ * own tuple as precisely as kb_query supports: a property or subject fact by
+ * its keys; a predicate fact by name plus, when a project `predicate_schema`
+ * or the built-in signature declares its arguments, `where` over the key
+ * arguments (the declared `key_arguments`, else the argument named `subject`,
+ * else the first), otherwise its full positional `args`. Pasted, it returns
+ * the fact and only facts sharing those key arguments.
  */
 export type SearchAnswerFact = SearchAnswerEntity & Readonly<{
     factKind?: string;
@@ -142,6 +154,23 @@ export declare const SEARCH_ANSWER_LIMITS: {
     /** Characters of a witness or unknown detail kept. */
     readonly detailChars: 240;
 };
+/**
+ * The declared arguments of a predicate fact's schema: a project
+ * `predicate_schema` or the built-in signature kb_query resolves `where`
+ * names against. `keyArguments` is empty when the schema declares none.
+ */
+export type PredicateFactSchema = Readonly<{
+    argumentNames: readonly string[];
+    keyArguments: readonly string[];
+}>;
+/**
+ * The `where` filter that selects the facts sharing a predicate fact's key
+ * arguments: the schema's `key_arguments`, else the argument named `subject`,
+ * else the first argument. Undefined when the schema does not fit the fact
+ * (arity) or no key argument has a value, so the caller falls back to
+ * positional args.
+ */
+export declare function predicateKeyFilter(args: readonly string[], schema: PredicateFactSchema): Record<string, string> | undefined;
 /**
  * The opening sentences of an ADR's Decision section (falling back to
  * Rationale, then to the first prose paragraph), as plain text of at most

package/dist/search-answer.d.ts.map

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

package/dist/search-answer.js

@@ -1,4 +1,5 @@
-import { escapeAtom, normalizeEntityId, parseEntityFromList, parseListOfLists, parseTriples, } from "./prolog/codec.js";
+import { effectiveFirmness } from "./decision-firmness.js";
+import { escapeAtom, normalizeEntityId, parseAtomList, parseEntityFromList, parseListOfLists, parseTriples, } from "./prolog/codec.js";
 import { isProvenanceStub } from "./provenance-stub.js";
 import { entityRowsGoal } from "./public/operations/discovery-entities.js";
 import { runOperationJsonQuery } from "./public/operations/prolog-json.js";
@@ -41,6 +42,7 @@ const ROW_KEYS = [
     "status",
     "fact_kind",
     "approved_by",
+    "firmness",
     "source",
     "sourceFile",
     "predicate_namespace",
@@ -84,30 +86,68 @@ function unique(ids) {
 }
 function brief(entity) {
     const status = text(entity.status);
+    const firmness = effectiveFirmness(entity.type, entity.firmness);
     return {
         id: text(entity.id),
         title: text(entity.title),
         ...(status ? { status } : {}),
+        ...(firmness ? { firmness } : {}),
     };
 }
 function queryCall(args) {
     return `kb_query(${JSON.stringify(args)})`;
 }
+/**
+ * The `where` filter that selects the facts sharing a predicate fact's key
+ * arguments: the schema's `key_arguments`, else the argument named `subject`,
+ * else the first argument. Undefined when the schema does not fit the fact
+ * (arity) or no key argument has a value, so the caller falls back to
+ * positional args.
+ */
+// implements REQ-kibi-query-fact-filters
+export function predicateKeyFilter(args, schema) {
+    const names = schema.argumentNames;
+    if (names.length === 0 || names.length !== args.length)
+        return undefined;
+    const declared = schema.keyArguments.filter((key) => names.includes(key));
+    const keys = declared.length > 0
+        ? declared
+        : [names.includes("subject") ? "subject" : names[0]];
+    const where = {};
+    for (const key of keys) {
+        const value = args[names.indexOf(key)] ?? "";
+        if (value !== "")
+            where[key] = value;
+    }
+    return Object.keys(where).length > 0 ? where : undefined;
+}
 /** Typed statement and follow-up query of a linked fact, by fact kind. */
 // implements REQ-kibi-query-fact-filters
-function factDetail(fact) {
+function factDetail(fact, schema) {
     const factKind = text(fact.fact_kind);
     const base = factKind ? { factKind } : {};
     const predicate = text(fact.predicate_name);
     if (factKind === "predicate" && predicate) {
         const args = Array.isArray(fact.predicate_args)
-            ? fact.predicate_args.map(text).join(", ")
-            : text(fact.predicate_args);
+            ? fact.predicate_args.map(text)
+            : undefined;
         const polarity = text(fact.polarity) === "deny" ? " [deny]" : "";
+        const namespace = text(fact.predicate_namespace);
+        const call = {
+            predicate,
+            ...(namespace && namespace !== "default" ? { namespace } : {}),
+        };
+        if (args !== undefined && args.length > 0) {
+            const where = schema ? predicateKeyFilter(args, schema) : undefined;
+            if (where)
+                call.where = where;
+            else
+                call.args = args.map((value) => (value === "" ? null : value));
+        }
         return {
             ...base,
-            claim: `${predicate}(${args})${polarity}`,
-            ask: queryCall({ predicate }),
+            claim: `${predicate}(${args?.join(", ") ?? text(fact.predicate_args)})${polarity}`,
+            ask: queryCall(call),
         };
     }
     const subjectKey = text(fact.subject_key);
@@ -128,6 +168,27 @@ function edgesGoal(ids) {
     const idList = ids.map((id) => `'${escapeAtom(id)}'`).join(",");
     return `findall([Rel,From,To], (member(Rel, [${ANSWER_RELATIONSHIPS.join(",")}]), kb_relationship(Rel, From, To), (member(From, [${idList}]); member(To, [${idList}]))), Edges)`;
 }
+/**
+ * For each predicate fact among `ids`, the argument names and key arguments
+ * of the schema kb_query resolves its `where` names against: the project
+ * `predicate_schema` of its namespace and name, else the built-in signature.
+ * Facts of other kinds, and predicates without a schema, yield no row.
+ */
+// implements REQ-kibi-query-fact-filters
+function factSchemasGoal(ids) {
+    const idList = ids.map((id) => `'${escapeAtom(id)}'`).join(",");
+    return `findall([FactId,Names,Keys], (member(FactId, [${idList}]), kb:predicate_fact(FactId, Ns, Name, _, _), ((kb:predicate_schema(SchemaId, Ns, Name, _, Names, _) -> ((kb_entity(SchemaId, fact, Props), memberchk(key_arguments=KeysRaw, Props), kb:normalize_term_atom_list(KeysRaw, Keys)) -> true ; Keys = [])) ; (kb:builtin_decision_predicate(Ns, Name, _, KeyPositions, _), kb:builtin_predicate_signature(Name, _, Names), findall(Key, (member(P, KeyPositions), nth1(P, Names, Key)), Keys)))), Schemas)`;
+}
+function parseFactSchemas(raw) {
+    const schemas = new Map();
+    for (const [id, names, keys] of parseTriples(raw ?? "[]")) {
+        schemas.set(normalizeEntityId(id), {
+            argumentNames: parseAtomList(names),
+            keyArguments: parseAtomList(keys),
+        });
+    }
+    return schemas;
+}
 /**
  * The part of the KB graph the answer reads, fetched in batches: each
  * `fetch` is one engine round trip for every id whose edges or row are not
@@ -489,6 +550,29 @@ async function fetchVerdicts(prolog, graph, rowIds, reqIds) {
         return undefined;
     }
 }
+/**
+ * The rows the answer still needs plus the schemas of the predicate facts
+ * among `factIds`, in one round trip. A schema lookup the engine cannot run
+ * leaves the rows loaded and every ask positional.
+ */
+// implements REQ-kibi-query-fact-filters
+async function fetchFactSchemas(graph, factIds, request) {
+    if (factIds.length === 0) {
+        await graph.fetch(request);
+        return new Map();
+    }
+    try {
+        const bindings = await graph.fetch({
+            ...request,
+            alsoGoal: factSchemasGoal(factIds),
+        });
+        return parseFactSchemas(bindings.Schemas);
+    }
+    catch {
+        await graph.fetch(request);
+        return new Map();
+    }
+}
 // implements REQ-bootstrap-provenance-stubs
 export async function buildSearchAnswer(prolog, matches, options = {}) {
     const limits = SEARCH_ANSWER_LIMITS;
@@ -551,13 +635,9 @@ export async function buildSearchAnswer(prolog, matches, options = {}) {
             continue;
         }
         if (owners.length === 0 && ["fact", "scenario", "symbol"].includes(type)) {
+            // A fact's claim and ask are filled in once its schema is known.
             if (ungoverned.length < limits.ungoverned)
-                ungoverned.push({
-                    ...brief(entity),
-                    ...(type === "fact" ? factDetail(entity) : {}),
-                    type,
-                    rank: index + 1,
-                });
+                ungoverned.push({ ...brief(entity), type, rank: index + 1 });
             else
                 truncated = true;
             continue;
@@ -689,7 +769,13 @@ export async function buildSearchAnswer(prolog, matches, options = {}) {
             exceptions: firstOf(into("exempts")),
         };
     });
-    await graph.fetch({
+    // The schemas of the linked and ungoverned predicate facts share this
+    // round trip, so each fact's ask can name its key arguments.
+    const factIds = unique([
+        ...ungoverned.filter((entry) => entry.type === "fact").map((e) => e.id),
+        ...plans.flatMap((plan) => plan.facts),
+    ]);
+    const schemas = await fetchFactSchemas(graph, factIds, {
         edges: plans.flatMap((plan) => plan.scenarios),
         rows: plans.flatMap((plan) => [
             ...plan.facts,
@@ -699,6 +785,18 @@ export async function buildSearchAnswer(prolog, matches, options = {}) {
             ...plan.directTests.slice(0, limits.perRequirement),
         ]),
     });
+    const detailedUngoverned = ungoverned.map((entry) => {
+        const row = entry.type === "fact" ? graph.row(entry.id) : null;
+        if (row === null)
+            return entry;
+        const { type, rank } = entry;
+        return {
+            ...brief(row),
+            ...factDetail(row, schemas.get(entry.id)),
+            type,
+            rank,
+        };
+    });
     // Tests linked to the requirement itself come first, then tests that
     // verify one of its scenarios; a test reached both ways counts as direct.
     const testVias = plans.map((plan) => {
@@ -738,7 +836,7 @@ export async function buildSearchAnswer(prolog, matches, options = {}) {
             via: req.via,
             facts: rowsOf(plan.facts).map((fact) => ({
                 ...brief(fact),
-                ...factDetail(fact),
+                ...factDetail(fact, schemas.get(text(fact.id))),
             })),
             scenarios: rowsOf(plan.scenarios).map(brief),
             tests: rowsOf(testIds[index] ?? []).map((row) => ({
@@ -769,17 +867,17 @@ export async function buildSearchAnswer(prolog, matches, options = {}) {
             ? verdicts.scope.syncedAt
             : null,
     };
-    ungoverned.sort((left, right) => left.rank - right.rank);
+    detailedUngoverned.sort((left, right) => left.rank - right.rank);
     const answer = {
         version: "kibi.search-answer.v1",
         governing,
         rationale,
         notGoverning,
         observations: observations.slice(0, limits.observations),
-        ungoverned,
+        ungoverned: detailedUngoverned,
         scope,
         truncated: truncated || graph.truncated,
-        note: answerNote(governing.length, ungoverned),
+        note: answerNote(governing.length, detailedUngoverned),
     };
     return fitSearchAnswer(answer, limits.maxBytes);
 }

package/dist/types/entities.d.ts

@@ -67,6 +67,8 @@ export type Requirement = BaseEntity & {
     approval_ref?: string;
     /** Why the requirement exists; explanation, not checked meaning. */
     rationale?: string;
+    /** How firmly it was decided; absent reads as default. */
+    firmness?: "firm" | "default" | "exploratory";
     /** Exception requirements only: claim keys of the exempted requirement it waives. */
     exempts_claims?: string[];
 };
@@ -78,6 +80,8 @@ export type TestEntity = BaseEntity & TestVerificationFields & {
 };
 export type ADR = BaseEntity & {
     type: "adr";
+    /** How firmly it was decided; absent reads as default. */
+    firmness?: "firm" | "default" | "exploratory";
 };
 export type Flag = BaseEntity & {
     type: "flag";

package/dist/types/entities.d.ts.map

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

package/dist/utils/kb-manifest.d.ts

@@ -20,6 +20,12 @@ export interface KbManifest {
      * Only these ids may carry `review:context-missing` without a violation.
      */
     contextAcknowledged?: string[];
+    /**
+     * Supersede edges (`FROM -> TO`) the schema 9 migration acknowledged as
+     * lacking a "Why this changed" section. An entity is exempt from
+     * supersedes-reason-missing only while every edge it has is listed here.
+     */
+    supersedesReasonAcknowledged?: string[];
 }
 export declare function defaultKbManifest(): KbManifest;
 export type KbManifestStatus = {

package/dist/utils/kb-manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"kb-manifest.d.ts","sourceRoot":"","sources":["../../src/utils/kb-manifest.ts"],"names":[],"mappings":"AA8BA;;;;;;;GAOG;AAEH,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC,MAAM,MAAM,uBAAuB,GAC/B,SAAS,GACT,WAAW,GACX,gBAAgB,CAAC;AAErB,MAAM,WAAW,UAAU;IACzB,uEAAuE;IACvE,eAAe,EAAE,MAAM,CAAC;IACxB,qEAAqE;IACrE,aAAa,EAAE,MAAM,CAAC;IACtB,0DAA0D;IAC1D,uBAAuB,EAAE,uBAAuB,CAAC;IACjD;;;OAGG;IACH,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;CAChC;AAED,wBAAgB,iBAAiB,IAAI,UAAU,CAM9C;AAED,MAAM,MAAM,gBAAgB,GACxB;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,UAAU,CAAC;IAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAClE;IACE,KAAK,EAAE,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;IACxC,QAAQ,EAAE,IAAI,CAAC;IACf,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAuDN,wBAAgB,oBAAoB,CAAC,aAAa,EAAE,MAAM,GAAG,gBAAgB,CAyD5E;AAED,wBAAgB,cAAc,CAAC,aAAa,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAGvE;AAED,8EAA8E;AAC9E,wBAAgB,uBAAuB,CAAC,aAAa,EAAE,MAAM,GAAG,UAAU,CAEzE;AASD,wBAAgB,eAAe,CAC7B,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,UAAU,GACnB,MAAM,CAIR"}
+{"version":3,"file":"kb-manifest.d.ts","sourceRoot":"","sources":["../../src/utils/kb-manifest.ts"],"names":[],"mappings":"AA8BA;;;;;;;GAOG;AAEH,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC,MAAM,MAAM,uBAAuB,GAC/B,SAAS,GACT,WAAW,GACX,gBAAgB,CAAC;AAErB,MAAM,WAAW,UAAU;IACzB,uEAAuE;IACvE,eAAe,EAAE,MAAM,CAAC;IACxB,qEAAqE;IACrE,aAAa,EAAE,MAAM,CAAC;IACtB,0DAA0D;IAC1D,uBAAuB,EAAE,uBAAuB,CAAC;IACjD;;;OAGG;IACH,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC/B;;;;OAIG;IACH,4BAA4B,CAAC,EAAE,MAAM,EAAE,CAAC;CACzC;AAED,wBAAgB,iBAAiB,IAAI,UAAU,CAM9C;AAED,MAAM,MAAM,gBAAgB,GACxB;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,UAAU,CAAC;IAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAClE;IACE,KAAK,EAAE,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;IACxC,QAAQ,EAAE,IAAI,CAAC;IACf,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AA+DN,wBAAgB,oBAAoB,CAAC,aAAa,EAAE,MAAM,GAAG,gBAAgB,CAyD5E;AAED,wBAAgB,cAAc,CAAC,aAAa,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAGvE;AAED,8EAA8E;AAC9E,wBAAgB,uBAAuB,CAAC,aAAa,EAAE,MAAM,GAAG,UAAU,CAEzE;AASD,wBAAgB,eAAe,CAC7B,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,UAAU,GACnB,MAAM,CAIR"}

package/dist/utils/kb-manifest.js

@@ -71,6 +71,7 @@ function validateManifest(parsed) {
         return null;
     }
     const acknowledged = parsed.contextAcknowledged;
+    const supersedesAcknowledged = parsed.supersedesReasonAcknowledged;
     return {
         manifestVersion,
         schemaVersion,
@@ -80,6 +81,11 @@ function validateManifest(parsed) {
                 contextAcknowledged: acknowledged.filter((id) => typeof id === "string"),
             }
             : {}),
+        ...(Array.isArray(supersedesAcknowledged)
+            ? {
+                supersedesReasonAcknowledged: supersedesAcknowledged.filter((id) => typeof id === "string"),
+            }
+            : {}),
     };
 }
 export function readKbManifestStatus(workspaceRoot) {

package/dist/utils/rule-registry.generated.d.ts

@@ -228,6 +228,27 @@ export declare const GENERATED_RULES: readonly [{
     readonly enforcementClass: "advisory";
     readonly category: "lifecycle";
     readonly diagnosticSeverity: "info";
+}, {
+    readonly name: "decision-firm-unreferenced";
+    readonly description: "A requirement or ADR marked firmness: firm must name the human words it rests on: origin.ref (or approval_ref on a requirement); Kibi checks that the reference is present, not that it is genuine";
+    readonly enforcementClass: "canonical";
+    readonly category: "integrity";
+}, {
+    readonly name: "decision-firm-superseded";
+    readonly description: "A requirement or ADR that supersedes a firm decision, retired or not, must itself be firm (and so carry a ref to the human who changed the rule); a default or exploratory replacement cannot overrule a firm decision";
+    readonly enforcementClass: "canonical";
+    readonly category: "lifecycle";
+}, {
+    readonly name: "supersedes-reason-missing";
+    readonly description: "A current requirement or ADR that supersedes another must explain why under a 'Why this changed' heading (at least 12 words of prose naming the evidence and answering the old decision's reasoning); supersede edges recorded before schema 9 are acknowledged in the manifest and exempt";
+    readonly enforcementClass: "canonical";
+    readonly category: "lifecycle";
+}, {
+    readonly name: "supersedes-reason-acknowledged";
+    readonly description: "Informational: how many current superseding requirements and ADRs have only supersede edges the schema 9 migration acknowledged without a 'Why this changed' section; one summary finding per check";
+    readonly enforcementClass: "advisory";
+    readonly category: "lifecycle";
+    readonly diagnosticSeverity: "info";
 }, {
     readonly name: "policy-ownership";
     readonly description: "When a plugin activated for kibi.check-policy.v1 declares ownership rules, every production symbol in a rule's file set must implement a current requirement grounded (requires_predicate) in one of the rule's predicates; projects without an activated check policy are unaffected";

package/dist/utils/rule-registry.generated.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rule-registry.generated.d.ts","sourceRoot":"","sources":["../../src/utils/rule-registry.generated.ts"],"names":[],"mappings":"AAUA,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA4UlB,CAAC"}
+{"version":3,"file":"rule-registry.generated.d.ts","sourceRoot":"","sources":["../../src/utils/rule-registry.generated.ts"],"names":[],"mappings":"AAUA,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAyWlB,CAAC"}

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

@@ -283,6 +283,31 @@ export const GENERATED_RULES = [
         category: "lifecycle",
         diagnosticSeverity: "info",
     },
+    {
+        name: "decision-firm-unreferenced",
+        description: "A requirement or ADR marked firmness: firm must name the human words it rests on: origin.ref (or approval_ref on a requirement); Kibi checks that the reference is present, not that it is genuine",
+        enforcementClass: "canonical",
+        category: "integrity",
+    },
+    {
+        name: "decision-firm-superseded",
+        description: "A requirement or ADR that supersedes a firm decision, retired or not, must itself be firm (and so carry a ref to the human who changed the rule); a default or exploratory replacement cannot overrule a firm decision",
+        enforcementClass: "canonical",
+        category: "lifecycle",
+    },
+    {
+        name: "supersedes-reason-missing",
+        description: "A current requirement or ADR that supersedes another must explain why under a 'Why this changed' heading (at least 12 words of prose naming the evidence and answering the old decision's reasoning); supersede edges recorded before schema 9 are acknowledged in the manifest and exempt",
+        enforcementClass: "canonical",
+        category: "lifecycle",
+    },
+    {
+        name: "supersedes-reason-acknowledged",
+        description: "Informational: how many current superseding requirements and ADRs have only supersede edges the schema 9 migration acknowledged without a 'Why this changed' section; one summary finding per check",
+        enforcementClass: "advisory",
+        category: "lifecycle",
+        diagnosticSeverity: "info",
+    },
     {
         name: "policy-ownership",
         description: "When a plugin activated for kibi.check-policy.v1 declares ownership rules, every production symbol in a rule's file set must implement a current requirement grounded (requires_predicate) in one of the rule's predicates; projects without an activated check policy are unaffected",

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

@@ -1,4 +1,4 @@
-export declare const LATEST_KB_SCHEMA_VERSION = 8;
+export declare const LATEST_KB_SCHEMA_VERSION = 9;
 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":"AAqBA,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":"AAuBA,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

@@ -18,7 +18,9 @@
 // implements REQ-003
 // Schema 8 requires body context on current entities and pins requirement
 // semantic_text so context sections never change a requirement's meaning.
-export const LATEST_KB_SCHEMA_VERSION = 8;
+// Schema 9 adds decision firmness on requirements and ADRs and requires a
+// "Why this changed" section on new supersedes.
+export const LATEST_KB_SCHEMA_VERSION = 9;
 // implements REQ-003
 export function normalizeSchemaVersion(schemaVersion) {
     if (schemaVersion === undefined || schemaVersion === null) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-cli",
-  "version": "2.20.0",
+  "version": "2.21.2",
   "type": "module",
   "description": "Kibi CLI for knowledge base management",
   "engines": {
@@ -235,7 +235,7 @@
     "fast-glob": "^3.2.12",
     "gray-matter": "^4.0.3",
     "js-yaml": "^4.1.0",
-    "kibi-core": "^0.21.0",
+    "kibi-core": "^0.21.1",
     "kibi-plugin-builtin": "^0.5.1",
     "kibi-plugin-sdk": "^0.5.0",
     "kibi-swipl": "^1.0.1",

package/schema/entities.pl

@@ -51,6 +51,10 @@ entity_property(req, approval_ref, string).
 entity_property(req, rationale, string).
 % Claim keys of the exempted requirement an exception waives (all when absent).
 entity_property(req, exempts_claims, list).
+% How firmly a requirement or ADR was decided: firm, default or exploratory.
+% Absent reads as default.
+entity_property(req, firmness, atom).
+entity_property(adr, firmness, atom).
 % Intended outcome of a scenario: success, rejection or error.
 entity_property(scenario, expects, atom).
 
@@ -143,6 +147,8 @@ optional_property(req, approved_by).
 optional_property(req, approval_ref).
 optional_property(req, rationale).
 optional_property(req, exempts_claims).
+optional_property(req, firmness).
+optional_property(adr, firmness).
 optional_property(test, verification_scope).
 optional_property(test, verification_perspective).
 optional_property(test, proof_contract).