kibi-cli 2.20.0 → 2.21.2

package/dist/decision-firmness.js

@@ -0,0 +1,115 @@
+/*
+ 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/>.
+*/
+/**
+ * Decision firmness: how firmly a requirement or ADR was decided, which tells
+ * a later agent whether it may supersede the decision on evidence or must ask
+ * a human first. This module is the one place that knows the values, the
+ * default and what a supersede must explain, so extraction, checks, search,
+ * query and migration agree.
+ */
+import { parseBodySections } from "./entity-body-context.js";
+/** Firmness values, firmest first. */
+// implements REQ-kb-decision-firmness
+export const FIRMNESS_VALUES = ["firm", "default", "exploratory"];
+/** The firmness of a decision that does not state one. */
+// implements REQ-kb-decision-firmness
+export const DEFAULT_FIRMNESS = "default";
+/** Entity types that carry firmness. */
+// implements REQ-kb-decision-firmness
+export const FIRMNESS_TYPES = ["req", "adr"];
+/** A supersede must explain itself under a heading starting with this. */
+// implements REQ-kb-decision-firmness
+export const WHY_THIS_CHANGED_HEADING = "Why this changed";
+/** The explanation needs at least this many words of prose. */
+// implements REQ-kb-decision-firmness
+export const MIN_WHY_CHANGED_WORDS = 12;
+const WHY_THIS_CHANGED = /^why\s+this\s+changed\b/i;
+/**
+ * How the manifest records one acknowledged supersede edge. Edges, not ids,
+ * are acknowledged, so a supersede added later to the same entity still has
+ * to explain itself.
+ */
+// implements REQ-kb-decision-firmness
+export function supersedeAcknowledgement(from, to) {
+    return `${from} -> ${to}`;
+}
+// implements REQ-kb-decision-firmness
+export function isFirmness(value) {
+    return (typeof value === "string" &&
+        FIRMNESS_VALUES.includes(value));
+}
+// implements REQ-kb-decision-firmness
+export function carriesFirmness(type) {
+    return (typeof type === "string" &&
+        FIRMNESS_TYPES.includes(type));
+}
+/**
+ * The firmness a decision is read with: the authored value, else `default`.
+ * Undefined for types that carry no firmness.
+ */
+// implements REQ-kb-decision-firmness
+export function effectiveFirmness(type, value) {
+    if (!carriesFirmness(type))
+        return undefined;
+    return isFirmness(value) ? value : DEFAULT_FIRMNESS;
+}
+/**
+ * The reference that makes a firm decision traceable to a human's words:
+ * `origin.ref`, or `approval_ref` on a requirement.
+ */
+// implements REQ-kb-decision-firmness
+export function firmnessRef(entity) {
+    const origin = entity.origin;
+    if (origin !== null && typeof origin === "object") {
+        const ref = origin.ref;
+        if (typeof ref === "string" && ref.trim() !== "")
+            return ref.trim();
+    }
+    if (entity.type === "req" &&
+        typeof entity.approval_ref === "string" &&
+        entity.approval_ref.trim() !== "") {
+        return entity.approval_ref.trim();
+    }
+    return undefined;
+}
+function wordCount(text) {
+    return text.split(/\s+/).filter((word) => /[\p{L}\p{N}]/u.test(word)).length;
+}
+/**
+ * Words of prose under the body's "Why this changed" heading (nested
+ * headings included), or 0 when the body has no such section.
+ */
+// implements REQ-kb-decision-firmness
+export function whyThisChangedWords(body) {
+    const sections = parseBodySections(body);
+    let level = null;
+    let words = 0;
+    for (const section of sections) {
+        if (level !== null && section.level > 0 && section.level <= level) {
+            level = null;
+        }
+        if (level === null &&
+            section.level > 0 &&
+            WHY_THIS_CHANGED.test(section.heading.replace(/^[*_`\s]+/, ""))) {
+            level = section.level;
+        }
+        if (level !== null)
+            words += wordCount(section.text);
+    }
+    return words;
+}

package/dist/extractors/markdown.d.ts

@@ -1,3 +1,4 @@
+import { type Firmness } from "../decision-firmness.js";
 import { type EntityOrigin } from "../public/entity-origin.js";
 import { type ProofBinding, type ProofContract } from "../public/proof-protocol.js";
 import { type ProofReceipt } from "../public/proof-receipt.js";
@@ -15,6 +16,7 @@ export interface ExtractedEntity {
     severity?: string;
     text_ref?: string;
     origin?: EntityOrigin;
+    firmness?: Firmness;
     semantic_text?: string;
     logic_claims?: string[];
     semantic_clauses?: string[];

package/dist/extractors/markdown.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../../src/extractors/markdown.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../../src/extractors/markdown.ts"],"names":[],"mappings":"AAsBA,OAAO,EAEL,KAAK,QAAQ,EAGd,MAAM,yBAAyB,CAAC;AAMjC,OAAO,EACL,KAAK,YAAY,EAElB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAGL,KAAK,YAAY,EACjB,KAAK,aAAa,EACnB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,KAAK,YAAY,EAElB,MAAM,4BAA4B,CAAC;AAuEpC,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,0BAA0B,CAAC,EAAE,4BAA4B,CAAC;IAC1D,qBAAqB,CAAC,EAAE,eAAe,GAAG,UAAU,GAAG,OAAO,CAAC;IAC/D,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kBAAkB,CAAC,EAAE,MAAM,GAAG,aAAa,GAAG,YAAY,CAAC;IAC3D,wBAAwB,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC;IACnD,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,OAAO,CAAC,EAAE,SAAS,GAAG,WAAW,GAAG,OAAO,CAAC;IAC5C,cAAc,CAAC,EAAE,aAAa,CAAC;IAC/B,cAAc,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IACzC,cAAc,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IAEzC,SAAS,CAAC,EACN,SAAS,GACT,gBAAgB,GAChB,aAAa,GACb,MAAM,GACN,kBAAkB,GAClB,WAAW,GACX,aAAa,GACb,MAAM,CAAC;IACX,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,IAAI,GAAG,KAAK,GAAG,IAAI,GAAG,KAAK,GAAG,IAAI,GAAG,KAAK,CAAC;IACtD,UAAU,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IAClD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC;IACpD,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,qBAAqB,CAAC,EAAE,MAAM,EAAE,CAAC;IACjC,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,kBAAkB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAC9C,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kBAAkB,CAAC,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;CACzD;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,eAAe,CAAC;IACxB,aAAa,EAAE,qBAAqB,EAAE,CAAC;IACvC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAuMD,qBAAa,gBAAiB,SAAQ,KAAK;IAOhC,QAAQ,EAAE,MAAM;IANlB,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,CAAC,EAAE,MAAM,CAAC;gBAG5B,OAAO,EAAE,MAAM,EACR,QAAQ,EAAE,MAAM,EACvB,OAAO,CAAC,EAAE;QACR,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB;IAYM,QAAQ;CAUlB;AA8CD;;;;;GAKG;AAEH,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQlE;AAED;;;;;GAKG;AAEH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE5D;AAkBD,wBAAgB,sBAAsB,CAEpC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,UAAU,EAAE,MAAM,GACjB,MAAM,EAAE,CAkDV;AA6iBD,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,gBAAgB,CAElB;AAGD,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB,CAatE;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CASjE;AASD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAQpE"}

package/dist/extractors/markdown.js

@@ -19,8 +19,9 @@ import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
 import Ajv from "ajv";
 import { load as yamlLoad } from "js-yaml";
+import { FIRMNESS_VALUES, carriesFirmness, isFirmness, } from "../decision-firmness.js";
 import { withoutContextSections } from "../entity-body-context.js";
-import { semanticClaimKey } from "../operations/semantic-advisor/clauses.js";
+import { deriveFactClaimKey, semanticClaimKey, } from "../operations/semantic-advisor/clauses.js";
 import { normalizeEntityOrigin, } from "../public/entity-origin.js";
 import { PROOF_BINDINGS_SCHEMA, PROOF_CONTRACT_SCHEMA, } from "../public/proof-protocol.js";
 import { proofReceiptHistoryErrors, } from "../public/proof-receipt.js";
@@ -511,6 +512,19 @@ function extractFromMarkdownContent(content, filePath) {
             }
             entity.rationale = data.rationale;
         }
+        // implements REQ-kb-decision-firmness
+        // How firmly a requirement or ADR was decided; absent reads as default.
+        if (data.firmness !== undefined) {
+            if (!carriesFirmness(type) || !isFirmness(data.firmness)) {
+                throw new FrontmatterError(carriesFirmness(type)
+                    ? `Invalid firmness; expected one of ${FIRMNESS_VALUES.join(", ")}`
+                    : "firmness is only allowed on type: req or adr", filePath, {
+                    classification: "Invalid Firmness",
+                    hint: "Use firm only for a rule a human stated (with origin.ref to their words), default for a delegated or agent choice, exploratory for a flagged guess; remove the field from other entity types.",
+                });
+            }
+            entity.firmness = data.firmness;
+        }
         if (type === "req" && Array.isArray(data.exempts_claims)) {
             entity.exempts_claims = data.exempts_claims.filter((value) => typeof value === "string");
         }
@@ -671,6 +685,7 @@ function extractFromMarkdownContent(content, filePath) {
                 hint: "Fix the entity fields so they match the public schema.",
             });
         }
+        deriveFactClaimKey(entity);
         if (entity.type === "fact" &&
             entity.claim_key !== undefined &&
             entity.claim_text !== undefined) {

package/dist/operations/migration/kb-sources.d.ts

@@ -47,7 +47,11 @@ export declare function withTopLevelField(content: string, key: string, value: s
  * change (the key gone, every other key parsing identically).
  */
 export declare function withoutTopLevelField(content: string, key: string): string | null;
-/** Replace a file's bytes atomically. */
+/**
+ * Replace a file's bytes atomically. A migration rewrite of an untracked
+ * `.kb/` source also rebinds its pending-source receipt, so the next sync
+ * reads the rewritten file instead of refusing it as hash drift.
+ */
 export declare function writeFileAtomically(filePath: string, content: string): void;
 export declare function readText(filePath: string): string | null;
 //# sourceMappingURL=kb-sources.d.ts.map

package/dist/operations/migration/kb-sources.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"kb-sources.d.ts","sourceRoot":"","sources":["../../../src/operations/migration/kb-sources.ts"],"names":[],"mappings":"AA8BA,OAAO,EAEL,KAAK,UAAU,EAEhB,MAAM,yBAAyB,CAAC;AAEjC,yEAAyE;AAEzE,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;IACtC,IAAI,EAAE,UAAU,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,yCAAyC;IACzC,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC,CAAC;AAuBH,0EAA0E;AAE1E,wBAAgB,qBAAqB,CACnC,aAAa,EAAE,MAAM,EACrB,KAAK,GAAE,SAAS,UAAU,EAAiB,GAC1C,gBAAgB,EAAE,CAkBpB;AAED,6DAA6D;AAE7D,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;IACtC,6DAA6D;IAC7D,MAAM,EAAE,MAAM,CAAC;IACf,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,IAAI,GAAG,MAAM,CAAC;CACpB,CAAC,CAAC;AAEH;;;;;GAKG;AAEH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAczE;AAUD;;;;;GAKG;AAEH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAe3E;AAeD;;;;;GAKG;AAEH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,GACZ,MAAM,GAAG,IAAI,CAyBf;AAQD;;;;;;GAMG;AAEH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,GACV,MAAM,GAAG,IAAI,CAsBf;AAED,yCAAyC;AAEzC,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAK3E;AAGD,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAMxD"}
+{"version":3,"file":"kb-sources.d.ts","sourceRoot":"","sources":["../../../src/operations/migration/kb-sources.ts"],"names":[],"mappings":"AA+BA,OAAO,EAEL,KAAK,UAAU,EAEhB,MAAM,yBAAyB,CAAC;AAGjC,yEAAyE;AAEzE,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;IACtC,IAAI,EAAE,UAAU,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,yCAAyC;IACzC,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC,CAAC;AAuBH,0EAA0E;AAE1E,wBAAgB,qBAAqB,CACnC,aAAa,EAAE,MAAM,EACrB,KAAK,GAAE,SAAS,UAAU,EAAiB,GAC1C,gBAAgB,EAAE,CAkBpB;AAED,6DAA6D;AAE7D,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;IACtC,6DAA6D;IAC7D,MAAM,EAAE,MAAM,CAAC;IACf,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,IAAI,GAAG,MAAM,CAAC;CACpB,CAAC,CAAC;AAEH;;;;;GAKG;AAEH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAczE;AAUD;;;;;GAKG;AAEH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAe3E;AAeD;;;;;GAKG;AAEH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,GACZ,MAAM,GAAG,IAAI,CAyBf;AAQD;;;;;;GAMG;AAEH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,GACV,MAAM,GAAG,IAAI,CAsBf;AAID;;;;GAIG;AAEH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAY3E;AAqBD,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAMxD"}

package/dist/operations/migration/kb-sources.js

@@ -15,11 +15,13 @@
  You should have received a copy of the GNU Affero General Public License
  along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */
+import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync, } from "node:fs";
 import path from "node:path";
 import { isDeepStrictEqual } from "node:util";
 import { load as loadYaml } from "js-yaml";
 import { ENTITY_LANES, KB_PATHS, } from "../../utils/kb-paths.js";
+import { republishPendingSourceReceipt } from "../mutation/source-authoring.js";
 function walkMarkdown(directory, files) {
     let entries;
     try {
@@ -214,13 +216,38 @@ export function withoutTopLevelField(content, key) {
     }
     return match === null ? content : `${slice.prefix}${text}${slice.suffix}`;
 }
-/** Replace a file's bytes atomically. */
+const KB_ROOT_DIRNAME = ".kb";
+/**
+ * Replace a file's bytes atomically. A migration rewrite of an untracked
+ * `.kb/` source also rebinds its pending-source receipt, so the next sync
+ * reads the rewritten file instead of refusing it as hash drift.
+ */
 // implements REQ-cli-schema-migration
 export function writeFileAtomically(filePath, content) {
     mkdirSync(path.dirname(filePath), { recursive: true });
     const tempPath = `${filePath}.kibi-migrate-${process.pid}-${Date.now()}`;
     writeFileSync(tempPath, content, "utf8");
     renameSync(tempPath, filePath);
+    const source = kbSourceLocation(filePath);
+    if (source === null)
+        return;
+    republishPendingSourceReceipt(source.workspaceRoot, source.relativePath, createHash("sha256").update(content, "utf8").digest("hex"));
+}
+/**
+ * The workspace root and workspace-relative path of a file under `.kb/`, or
+ * `null` for a file outside any knowledge root.
+ */
+function kbSourceLocation(filePath) {
+    const absolute = path.resolve(filePath);
+    const segments = absolute.split(path.sep);
+    const index = segments.lastIndexOf(KB_ROOT_DIRNAME);
+    if (index <= 0)
+        return null;
+    const workspaceRoot = segments.slice(0, index).join(path.sep) || path.sep;
+    return {
+        workspaceRoot,
+        relativePath: segments.slice(index).join("/"),
+    };
 }
 // implements REQ-cli-schema-migration
 export function readText(filePath) {

package/dist/operations/migration/schema6.d.ts

@@ -4,6 +4,8 @@ import { CLOSE_SUPERSEDED_REQUIREMENTS_CODE, MIGRATION_SYNC_ACTION_ID, MIGRATION
 export declare const ORIGIN_SCHEMA_VERSION = 6;
 /** The KB schema generation that requires body context on current entities. */
 export declare const BODY_CONTEXT_SCHEMA_VERSION = 8;
+/** The KB schema generation that adds decision firmness. */
+export declare const DECISION_FIRMNESS_SCHEMA_VERSION = 9;
 /** Automatic: re-derive a drifted inventory with the current advisor. */
 export declare const SEMANTIC_INVENTORY_REDERIVE_CODE = "semantic_inventory_rederive";
 /** Review: a drifted inventory Kibi cannot re-derive safely. */

package/dist/operations/migration/schema6.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema6.d.ts","sourceRoot":"","sources":["../../../src/operations/migration/schema6.ts"],"names":[],"mappings":"AAuBA,OAAO,EACL,KAAK,eAAe,EAErB,MAAM,2CAA2C,CAAC;AACnD,OAAO,EAEL,kCAAkC,EAClC,wBAAwB,EACxB,mBAAmB,EAEnB,wBAAwB,EAOzB,MAAM,kDAAkD,CAAC;AAoC1D,gEAAgE;AAEhE,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAEvC,+EAA+E;AAE/E,eAAO,MAAM,2BAA2B,IAAI,CAAC;AAE7C,yEAAyE;AAEzE,eAAO,MAAM,gCAAgC,gCAAgC,CAAC;AAC9E,gEAAgE;AAEhE,eAAO,MAAM,8BAA8B,8BAA8B,CAAC;AAC1E,yEAAyE;AAEzE,eAAO,MAAM,2BAA2B,2BAA2B,CAAC;AAEpE,eAAO,MAAM,gCAAgC,2BAA2B,CAAC;AACzE,OAAO,EACL,kCAAkC,EAClC,wBAAwB,EACxB,mBAAmB,EACnB,wBAAwB,GACzB,CAAC;AAsEF;;;GAGG;AAEH,wBAAgB,+BAA+B,CAC7C,aAAa,EAAE,MAAM,GACpB,KAAK,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAsDnE;AAGD,MAAM,MAAM,wBAAwB,GAAG,QAAQ,CAAC;IAC9C,OAAO,EAAE,SAAS,eAAe,EAAE,CAAC;IACpC,uDAAuD;IACvD,sBAAsB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CAChC,CAAC,CAAC;AAEH;;;;;;GAMG;AAEH,wBAAgB,6BAA6B,CAAC,KAAK,EAAE;IACnD,aAAa,EAAE,MAAM,CAAC;IACtB,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;CACrC,GAAG,wBAAwB,CA6J3B;AAED;;;;;;GAMG;AAEH,wBAAgB,2BAA2B,CAAC,aAAa,EAAE,MAAM,GAAG;IAClE,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,sBAAsB,EAAE,MAAM,EAAE,CAAC;CAClC,CAoCA;AAED,qEAAqE;AAErE,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,eAAe,CAEjB;AA0CD,KAAK,YAAY,GAAG,QAAQ,CAAC;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB,CAAC,CAAC;AAEH,4DAA4D;AAE5D,wBAAsB,2BAA2B,CAC/C,MAAM,EAAE,eAAe,EACvB,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC,IAAI,CAAC,CAsEf;AAGD,eAAO,MAAM,uBAAuB,EAAE,WAAW,CAAC,MAAM,CAStD,CAAC"}
+{"version":3,"file":"schema6.d.ts","sourceRoot":"","sources":["../../../src/operations/migration/schema6.ts"],"names":[],"mappings":"AAuBA,OAAO,EACL,KAAK,eAAe,EAErB,MAAM,2CAA2C,CAAC;AACnD,OAAO,EAEL,kCAAkC,EAClC,wBAAwB,EACxB,mBAAmB,EAEnB,wBAAwB,EAOzB,MAAM,kDAAkD,CAAC;AAyC1D,gEAAgE;AAEhE,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAEvC,+EAA+E;AAE/E,eAAO,MAAM,2BAA2B,IAAI,CAAC;AAE7C,4DAA4D;AAE5D,eAAO,MAAM,gCAAgC,IAAI,CAAC;AAElD,yEAAyE;AAEzE,eAAO,MAAM,gCAAgC,gCAAgC,CAAC;AAC9E,gEAAgE;AAEhE,eAAO,MAAM,8BAA8B,8BAA8B,CAAC;AAC1E,yEAAyE;AAEzE,eAAO,MAAM,2BAA2B,2BAA2B,CAAC;AAEpE,eAAO,MAAM,gCAAgC,2BAA2B,CAAC;AACzE,OAAO,EACL,kCAAkC,EAClC,wBAAwB,EACxB,mBAAmB,EACnB,wBAAwB,GACzB,CAAC;AAwEF;;;GAGG;AAEH,wBAAgB,+BAA+B,CAC7C,aAAa,EAAE,MAAM,GACpB,KAAK,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAsDnE;AAGD,MAAM,MAAM,wBAAwB,GAAG,QAAQ,CAAC;IAC9C,OAAO,EAAE,SAAS,eAAe,EAAE,CAAC;IACpC,uDAAuD;IACvD,sBAAsB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CAChC,CAAC,CAAC;AAEH;;;;;;GAMG;AAEH,wBAAgB,6BAA6B,CAAC,KAAK,EAAE;IACnD,aAAa,EAAE,MAAM,CAAC;IACtB,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;CACrC,GAAG,wBAAwB,CAoM3B;AAED;;;;;;GAMG;AAEH,wBAAgB,2BAA2B,CAAC,aAAa,EAAE,MAAM,GAAG;IAClE,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,sBAAsB,EAAE,MAAM,EAAE,CAAC;CAClC,CAoCA;AAED,qEAAqE;AAErE,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,eAAe,CAEjB;AA0CD,KAAK,YAAY,GAAG,QAAQ,CAAC;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB,CAAC,CAAC;AAEH,4DAA4D;AAE5D,wBAAsB,2BAA2B,CAC/C,MAAM,EAAE,eAAe,EACvB,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC,IAAI,CAAC,CA0Ef;AAGD,eAAO,MAAM,uBAAuB,EAAE,WAAW,CAAC,MAAM,CAUtD,CAAC"}

package/dist/operations/migration/schema6.js

@@ -27,12 +27,16 @@ import { applyOriginBackfill, planOriginBackfill } from "./origin-backfill.js";
 import { POLARITY_VALUE_BACKFILL_CODE, applyPolarityValueBackfill, planPolarityValueBackfill, } from "./polarity-values.js";
 import { applySourcePathRepairs, findSourceRepairs, plannedSourcePathRepairs, } from "./source-paths.js";
 import { applySupersededClosures, planSupersededClosures, } from "./superseded-closure.js";
+import { SUPERSEDES_REASON_ACKNOWLEDGE_CODE, applySupersedesReasonAcknowledgement, planSupersedesReasonAcknowledgement, } from "./supersedes-reason.js";
 /** The KB schema generation that introduced entity `origin`. */
 // implements REQ-kibi-schema6-migration, REQ-cli-schema-migration
 export const ORIGIN_SCHEMA_VERSION = 6;
 /** The KB schema generation that requires body context on current entities. */
 // implements REQ-kb-entity-body-context, REQ-cli-schema-migration
 export const BODY_CONTEXT_SCHEMA_VERSION = 8;
+/** The KB schema generation that adds decision firmness. */
+// implements REQ-kb-decision-firmness, REQ-cli-schema-migration
+export const DECISION_FIRMNESS_SCHEMA_VERSION = 9;
 /** Automatic: re-derive a drifted inventory with the current advisor. */
 // implements REQ-kibi-schema6-migration, REQ-cli-schema-migration
 export const SEMANTIC_INVENTORY_REDERIVE_CODE = "semantic_inventory_rederive";
@@ -88,7 +92,7 @@ function reviewAction(plan) {
         safety: "review",
         invocation: {
             kind: "review",
-            instruction: `${plan.requirementId} (${plan.path}) no longer matches the current semantic advisor and cannot be re-derived automatically: ${plan.reasons.join("; ")}. Fix it by hand: run \`kibi model --input -\` with {"mode":"analyze","payload":{"type":"req","id":"${plan.requirementId}","properties":<the requirement's current properties>}} to get the current inventory; re-ground or remove each listed grounding link (kb_delete with the relationship) so modeled claims and requires_* links match one to one; kb_upsert the requirement with the returned semantic_inventory, logic_claims and semantic_source_hash (keep modeled only for claims that still have a grounding fact with the same claim_key); then run kibi sync.`,
+            instruction: `${plan.requirementId} (${plan.path}) no longer matches the current semantic advisor and cannot be re-derived automatically: ${plan.reasons.join("; ")}. Fix it in ${plan.path} itself: kibi sync rejects this requirement, so store-backed tools (kb_upsert, kb_delete) cannot see it until it compiles. In its front matter, write the re-derived contract from this action's evidence.contract (semantic_inventory, logic_claims, semantic_source_hash and their version fields), then make modeled claims and requires_* links match one to one: re-ground or remove each listed grounding link, and keep a claim modeled only while a grounding fact with the same claim_key remains. Run kibi sync to confirm. To see how the advisor reads the prose, run \`kibi model --input -\` with {"mode":"analyze","type":"req","id":"${plan.requirementId}","text":<the requirement's semantic_text, or its statement when it has none>}.`,
         },
         affectedEntityIds: [plan.requirementId],
         affectedFiles: [plan.path],
@@ -99,6 +103,8 @@ function reviewAction(plan) {
             reasons: plan.reasons,
             summary: plan.summary,
             changes: plan.changes.filter((change) => change.change !== "kept"),
+            contract: plan.contract,
+            contractHash: plan.contractHash,
         },
     });
 }
@@ -249,6 +255,38 @@ export function buildSchema6MigrationFragment(input) {
             }));
         }
     }
+    // Schema 9: acknowledge supersedes recorded before they had to explain
+    // themselves. Manifest only; no source changes and no reason is written.
+    if (input.currentSchemaVersion === null ||
+        input.currentSchemaVersion < DECISION_FIRMNESS_SCHEMA_VERSION) {
+        const unexplained = planSupersedesReasonAcknowledgement(input.workspaceRoot);
+        if (unexplained.length > 0) {
+            const id = "supersedes-reason-acknowledge";
+            // Not a source rewrite, but the schema upgrade and the store sync
+            // must wait for it like one: the bumped schema blocks without it.
+            sourceRewriteActionIds.push(id);
+            actions.push(migrationAction({
+                id,
+                code: SUPERSEDES_REASON_ACKNOWLEDGE_CODE,
+                category: "schema",
+                safety: "automatic",
+                autoApplicable: true,
+                invocation: {
+                    kind: "cli",
+                    command_argv: ["kibi", "migrate", "--yes"],
+                },
+                affectedEntityIds: unexplained.map((row) => row.id),
+                affectedFiles: [".kb/manifest.json"],
+                postconditions: [{ rule: "supersedes-reason-missing", findings: 0 }],
+                evidence: {
+                    reason: "Schema 9 blocks a current requirement or ADR that supersedes another without a 'Why this changed' section. Existing ones are acknowledged in the manifest (counted by supersedes-reason-acknowledged); no reason is invented.",
+                    count: unexplained.length,
+                    byType: countByType(unexplained),
+                    preserves: "every authored source file",
+                },
+            }));
+        }
+    }
     const drift = planInventoryRederivation(input.workspaceRoot);
     for (const plan of drift) {
         const action = plan.safe ? rederiveAction(plan) : reviewAction(plan);
@@ -397,6 +435,10 @@ export async function applySchema6MigrationAction(action, context) {
             applyContextMissingTags(context.workspaceRoot);
             return;
         }
+        case SUPERSEDES_REASON_ACKNOWLEDGE_CODE: {
+            applySupersedesReasonAcknowledgement(context.workspaceRoot);
+            return;
+        }
         case SEMANTIC_INVENTORY_REDERIVE_CODE: {
             const requirementId = action.affectedEntityIds[0];
             if (requirementId === undefined)
@@ -440,6 +482,7 @@ export const SCHEMA6_AUTOMATIC_CODES = new Set([
     POLARITY_VALUE_BACKFILL_CODE,
     SEMANTIC_TEXT_PIN_CODE,
     CONTEXT_MISSING_TAG_CODE,
+    SUPERSEDES_REASON_ACKNOWLEDGE_CODE,
     SEMANTIC_INVENTORY_REDERIVE_CODE,
     ENTITY_ORIGIN_BACKFILL_CODE,
     CLOSE_SUPERSEDED_REQUIREMENTS_CODE,

package/dist/operations/migration/supersedes-reason.d.ts

@@ -0,0 +1,26 @@
+/** Migration action code for the schema 9 acknowledgement. */
+export declare const SUPERSEDES_REASON_ACKNOWLEDGE_CODE = "supersedes_reason_acknowledge";
+/** One superseding decision the migration acknowledges. */
+export type SupersedesReasonTarget = Readonly<{
+    id: string;
+    type: string;
+    path: string;
+    /** The supersede edges to acknowledge, as the manifest records them. */
+    edges: readonly string[];
+}>;
+/**
+ * Superseding requirements and ADRs without a "Why this changed" section
+ * whose supersede edges the manifest does not acknowledge yet, retired ones
+ * included. Nothing in the sources changes: no reason is written, the
+ * manifest only records that these edges predate the rule. Read-only.
+ */
+export declare function planSupersedesReasonAcknowledgement(workspaceRoot: string): SupersedesReasonTarget[];
+/** The manifest list with the targets' edges added, sorted and unique. */
+export declare function mergeSupersedesAcknowledgements(existing: readonly string[] | undefined, targets: readonly SupersedesReasonTarget[]): string[];
+/**
+ * Record the acknowledged edges in the manifest; returns how many entities
+ * were acknowledged. Without a manifest there is no schema to upgrade from,
+ * so it refuses rather than report an acknowledgement it did not write.
+ */
+export declare function applySupersedesReasonAcknowledgement(workspaceRoot: string): number;
+//# sourceMappingURL=supersedes-reason.d.ts.map

package/dist/operations/migration/supersedes-reason.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"supersedes-reason.d.ts","sourceRoot":"","sources":["../../../src/operations/migration/supersedes-reason.ts"],"names":[],"mappings":"AA0BA,8DAA8D;AAE9D,eAAO,MAAM,kCAAkC,kCACd,CAAC;AAElC,2DAA2D;AAE3D,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC;IAC5C,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,wEAAwE;IACxE,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1B,CAAC,CAAC;AAEH;;;;;GAKG;AAEH,wBAAgB,mCAAmC,CACjD,aAAa,EAAE,MAAM,GACpB,sBAAsB,EAAE,CAgB1B;AAED,0EAA0E;AAE1E,wBAAgB,+BAA+B,CAC7C,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,EACvC,OAAO,EAAE,SAAS,sBAAsB,EAAE,GACzC,MAAM,EAAE,CAIV;AAED;;;;GAIG;AAEH,wBAAgB,oCAAoC,CAClD,aAAa,EAAE,MAAM,GACpB,MAAM,CAiBR"}

package/dist/operations/migration/supersedes-reason.js

@@ -0,0 +1,69 @@
+/*
+ Kibi — repo-local, per-branch, queryable long-term memory for software projects
+ Copyright (C) 2026 Piotr Franczyk
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Affero General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License
+ along with this program.  If not, see <https://www.gnu.org/licenses/>.
+*/
+import { authoredSupersedes, listDecisionEntities, supersedeAcknowledgements, unexplainedSupersedes, } from "../../public/operations/decision-firmness.js";
+import { readKbManifest, writeKbManifest } from "../../utils/kb-manifest.js";
+/** Migration action code for the schema 9 acknowledgement. */
+// implements REQ-kb-decision-firmness, REQ-cli-schema-migration
+export const SUPERSEDES_REASON_ACKNOWLEDGE_CODE = "supersedes_reason_acknowledge";
+/**
+ * Superseding requirements and ADRs without a "Why this changed" section
+ * whose supersede edges the manifest does not acknowledge yet, retired ones
+ * included. Nothing in the sources changes: no reason is written, the
+ * manifest only records that these edges predate the rule. Read-only.
+ */
+// implements REQ-kb-decision-firmness, REQ-cli-schema-migration
+export function planSupersedesReasonAcknowledgement(workspaceRoot) {
+    const entities = listDecisionEntities(workspaceRoot);
+    const known = new Set(readKbManifest(workspaceRoot)?.supersedesReasonAcknowledged ?? []);
+    const edges = authoredSupersedes(workspaceRoot, entities);
+    return unexplainedSupersedes(entities, edges)
+        .map((entity) => ({
+        id: entity.id,
+        type: entity.type,
+        path: entity.path,
+        edges: supersedeAcknowledgements(entity.id, edges).filter((edge) => !known.has(edge)),
+    }))
+        .filter((target) => target.edges.length > 0);
+}
+/** The manifest list with the targets' edges added, sorted and unique. */
+// implements REQ-kb-decision-firmness
+export function mergeSupersedesAcknowledgements(existing, targets) {
+    return [
+        ...new Set([...(existing ?? []), ...targets.flatMap((t) => t.edges)]),
+    ].sort();
+}
+/**
+ * Record the acknowledged edges in the manifest; returns how many entities
+ * were acknowledged. Without a manifest there is no schema to upgrade from,
+ * so it refuses rather than report an acknowledgement it did not write.
+ */
+// implements REQ-kb-decision-firmness, REQ-cli-schema-migration
+export function applySupersedesReasonAcknowledgement(workspaceRoot) {
+    const targets = planSupersedesReasonAcknowledgement(workspaceRoot);
+    if (targets.length === 0)
+        return 0;
+    const manifest = readKbManifest(workspaceRoot);
+    if (manifest === null) {
+        throw new Error("Cannot acknowledge existing supersedes without .kb/manifest.json; run 'kibi migrate --yes', which writes the manifest and the acknowledgement together.");
+    }
+    writeKbManifest(workspaceRoot, {
+        ...manifest,
+        supersedesReasonAcknowledged: mergeSupersedesAcknowledgements(manifest.supersedesReasonAcknowledged, targets),
+    });
+    return targets.length;
+}

package/dist/operations/modeling/predicate-applyplan.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"predicate-applyplan.d.ts","sourceRoot":"","sources":["../../../src/operations/modeling/predicate-applyplan.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAEV,wBAAwB,EACxB,wBAAwB,EACxB,mBAAmB,EACnB,0BAA0B,EAC1B,qBAAqB,EACtB,MAAM,sBAAsB,CAAC;AAQ9B,wBAAgB,eAAe,CAC7B,MAAM,EAAE,wBAAwB,EAChC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,gBAAgB,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAM,EACvD,YAAY,CAAC,EAAE,QAAQ,GAAG,MAAM,EAChC,WAAW,CAAC,EAAE;IACZ,WAAW,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC;IACtC,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,eAAe,CAAC,EAAE,wBAAwB,CAAC;IAC3C,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC,GACA,mBAAmB,CAuLrB;AAGD,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,mBAAmB,EAC/B,IAAI,EAAE,qBAAqB,GAC1B,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CA0ChC;AAGD,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,aAAa,EAAE,MAAM,GAAG,SAAS,EACjC,SAAS,CAAC,EAAE,MAAM,EAClB,mBAAmB,GAAE,SAAS,MAAM,EAAO,GAC1C,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAuBhC;AAoBD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,qBAAqB,GAC1B,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAwBhC;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GACd,0BAA0B,CAoE5B"}
+{"version":3,"file":"predicate-applyplan.d.ts","sourceRoot":"","sources":["../../../src/operations/modeling/predicate-applyplan.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAEV,wBAAwB,EACxB,wBAAwB,EACxB,mBAAmB,EACnB,0BAA0B,EAC1B,qBAAqB,EACtB,MAAM,sBAAsB,CAAC;AAQ9B,wBAAgB,eAAe,CAC7B,MAAM,EAAE,wBAAwB,EAChC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,gBAAgB,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAM,EACvD,YAAY,CAAC,EAAE,QAAQ,GAAG,MAAM,EAChC,WAAW,CAAC,EAAE;IACZ,WAAW,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC;IACtC,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,eAAe,CAAC,EAAE,wBAAwB,CAAC;IAC3C,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC,GACA,mBAAmB,CAuLrB;AAGD,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,mBAAmB,EAC/B,IAAI,EAAE,qBAAqB,GAC1B,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAkDhC;AAGD,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,aAAa,EAAE,MAAM,GAAG,SAAS,EACjC,SAAS,CAAC,EAAE,MAAM,EAClB,mBAAmB,GAAE,SAAS,MAAM,EAAO,GAC1C,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAuBhC;AAoBD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,qBAAqB,GAC1B,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAwBhC;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GACd,0BAA0B,CAoE5B"}

package/dist/operations/modeling/predicate-applyplan.js

@@ -1,4 +1,4 @@
-import { semanticClaimKey } from "../semantic-advisor/clauses.js";
+import { normalizeSemanticClause, semanticClaimKey, } from "../semantic-advisor/clauses.js";
 import { exactLauncherPredicateArgs } from "../semantic-advisor/predicate-rules-launcher.js";
 import { aggregateBindingProvenance, bindingCanBeApplied, classifyBinding, isGenericPlaceholder, isParticipantArgumentType, } from "./predicate-bindings.js";
 import { inferArgs } from "./predicate-inference.js";
@@ -190,11 +190,19 @@ export function buildPredicateApplyPlan(suggestion, args) {
                     ? { subject_key: suggestion.subject_key }
                     : {}),
                 predicate_name: suggestion.predicate_name,
+                // The schema's namespace, so the fact conforms to the project
+                // schema it was planned from rather than to default:<name>.
+                ...(suggestion.schema.predicate_namespace
+                    ? { predicate_namespace: suggestion.schema.predicate_namespace }
+                    : {}),
                 predicate_args: suggestion.predicate_args,
                 canonical_key: suggestion.canonical_key,
                 polarity: suggestion.polarity,
                 claim_key: claimKey,
-                claim_text: args.text.trim(),
+                // The ledger stores the clause without its sentence punctuation, and
+                // the proof compares the fact's claim_text with the ledger entry
+                // verbatim, so the fact quotes the same normalised clause.
+                claim_text: normalizeSemanticClause(args.text),
             },
             relationships: [],
         },

package/dist/operations/modeling/predicate-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"predicate-loader.d.ts","sourceRoot":"","sources":["../../../src/operations/modeling/predicate-loader.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0CAA0C,CAAC;AAK3E,OAAO,KAAK,EACV,wBAAwB,EACxB,mBAAmB,EACpB,MAAM,sBAAsB,CAAC;AAI9B,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAExE;AAGD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,wBAAwB,GAAG,IAAI,CACxE,wBAAwB,EACxB,UAAU,CACX,GAAG;IACF,WAAW,EAAE,mBAAmB,CAAC;CAClC,CA6BA;AAGD,wBAAsB,4BAA4B,CAChD,MAAM,EAAE,UAAU,GAAG,IAAI,EACzB,sBAAsB,EAAE,OAAO,EAC/B,QAAQ,EAAE,MAAM,EAAE,GACjB,OAAO,CAAC,wBAAwB,EAAE,CAAC,CAwBrC;AAGD,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,wBAAwB,EAAE,CA0D5B;AAGD,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,mBAAmB,GAAG,SAAS,CAOjC;AAGD,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE,CAQpD"}
+{"version":3,"file":"predicate-loader.d.ts","sourceRoot":"","sources":["../../../src/operations/modeling/predicate-loader.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0CAA0C,CAAC;AAK3E,OAAO,KAAK,EACV,wBAAwB,EACxB,mBAAmB,EACpB,MAAM,sBAAsB,CAAC;AAI9B,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAExE;AAGD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,wBAAwB,GAAG,IAAI,CACxE,wBAAwB,EACxB,UAAU,CACX,GAAG;IACF,WAAW,EAAE,mBAAmB,CAAC;CAClC,CAgCA;AAGD,wBAAsB,4BAA4B,CAChD,MAAM,EAAE,UAAU,GAAG,IAAI,EACzB,sBAAsB,EAAE,OAAO,EAC/B,QAAQ,EAAE,MAAM,EAAE,GACjB,OAAO,CAAC,wBAAwB,EAAE,CAAC,CAwBrC;AAGD,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,wBAAwB,EAAE,CAoE5B;AAGD,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,mBAAmB,GAAG,SAAS,CAOjC;AAGD,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE,CAQpD"}

package/dist/operations/modeling/predicate-loader.js

@@ -10,6 +10,9 @@ export function schemaForCandidate(schema) {
     return {
         id: schema.id,
         predicate_name: schema.predicate_name,
+        ...(schema.predicate_namespace
+            ? { predicate_namespace: schema.predicate_namespace }
+            : {}),
         title: schema.title,
         description: schema.description,
         argument_names: schema.argument_names,
@@ -67,10 +70,18 @@ export function predicateSchemaFromEntity(entity) {
     const argumentDescriptions = stringArray(entity.argument_descriptions);
     const keyArguments = stringArray(entity.key_arguments);
     const vocabulary = predicateVocabularyFromEntity(entity);
+    // A project schema's namespace is part of the predicate signature the
+    // conformance rule checks, so a planned fact has to carry it.
+    const predicateNamespace = normalizeOptionalString(typeof entity.predicate_namespace === "string"
+        ? entity.predicate_namespace
+        : undefined);
     return [
         {
             id: String(entity.id ?? hashId("FACT-SCHEMA", [predicateName])),
             predicate_name: predicateName,
+            ...(predicateNamespace && predicateNamespace !== "default"
+                ? { predicate_namespace: predicateNamespace }
+                : {}),
             title: String(entity.title ?? predicateName),
             description: String(entity.description ??
                 `Project-local ${predicateName} predicate schema.`),

package/dist/operations/modeling/predicate-types.d.ts

@@ -6,6 +6,8 @@ export interface PredicateUsageHints {
 export interface PredicateSchemaCandidate {
     id: string;
     predicate_name: string;
+    /** The schema's predicate_namespace; absent for the default namespace. */
+    predicate_namespace?: string;
     title: string;
     description: string;
     argument_names: string[];
@@ -128,7 +130,30 @@ export interface ExistingClaimGrounding {
     };
     factId: string;
     factKind: string | null;
+    /** The stored claim_key of the grounding fact. */
     claimKey: string;
+    /** The stored canonical_key of the grounding fact (predicate facts), else null. */
+    canonicalKey: string | null;
+    /**
+     * How the fact was recognised as grounding this claim: the same claim_key
+     * (the same proposition text), or the same canonical_key as the recommended
+     * candidate (the same predicate tuple stated in other words).
+     */
+    matchedBy: "claim_key" | "canonical_key";
+}
+/**
+ * A stored decision-predicate fact of a current requirement that agrees with
+ * the recommended candidate on every key argument and decides the opposite,
+ * found when no hash-bound plan carried the contradiction analysis.
+ */
+export interface CandidateDecisionConflict {
+    requirementId: string;
+    factId: string;
+    /** The stored fact's effective decision. */
+    effect: string;
+    /** The candidate's effective decision. */
+    proposedEffect: string;
+    canonicalKey: string;
 }
 export interface SuggestPredicatesResult {
     content: Array<{
@@ -143,7 +168,7 @@ export interface SuggestPredicatesResult {
         requirementId: string | null;
         subject: string;
         candidates: PredicateSuggestion[];
-        recommendedAction: "apply_requires_predicate" | "provide_argument_bindings" | "resolve_schema_reference" | "record_ontology_gap" | "review_nonlogical" | "replace_grounding";
+        recommendedAction: "apply_requires_predicate" | "provide_argument_bindings" | "resolve_schema_reference" | "record_ontology_gap" | "review_nonlogical" | "replace_grounding" | "extend_requirement" | "keep_existing_grounding";
         recommendedPredicateSchema: RecommendedPredicateSchema | null;
         applyPlan: Array<Record<string, unknown>>;
         relationshipPlan: Record<string, unknown> | null;
@@ -156,6 +181,12 @@ export interface SuggestPredicatesResult {
         /** The planned predicate fact id a requires_predicate link must target (never a candidate id). */
         relationshipTarget?: string | null;
         existingGrounding?: ExistingClaimGrounding[];
+        /**
+         * Stored decision facts of current requirements that contradict the
+         * recommended candidate on its key arguments; empty when a plan carried
+         * the contradiction analysis or no complete candidate was found.
+         */
+        decisionConflicts?: CandidateDecisionConflict[];
         replacementPlan?: Record<string, unknown> | null;
         /** On provide_argument_bindings: one hint per unbound argument of the recommended candidate. */
         bindingHints?: BindingHint[];