kibi-cli 2.21.0 → 2.21.2

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.21.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).

package/src/public/operations/check-executor.ts

@@ -41,6 +41,7 @@ import {
   stagedEntityIdStyleDiagnostics,
 } from "./check-helpers.js";
 import { collectCheckPolicyViolations } from "./check-policy-rules.js";
+import { collectDecisionFirmnessViolations } from "./decision-firmness.js";
 import { executeStatus } from "./discovery-executors.js";
 import { collectEntityContextViolations } from "./entity-context.js";
 import {
@@ -375,6 +376,10 @@ export async function executeCheck(
       rulesAllowlist,
       workspaceRoot,
     );
+    const decisionFirmnessFindings = collectDecisionFirmnessViolations(
+      rulesAllowlist,
+      workspaceRoot,
+    );
     const checkPolicyFindings = await collectCheckPolicyViolations(
       prolog,
       rulesAllowlist,
@@ -388,6 +393,7 @@ export async function executeCheck(
       ...predicateConformanceFindings,
       ...originReviewFindings,
       ...entityContextFindings,
+      ...decisionFirmnessFindings,
       ...checkPolicyFindings,
     ]);
     const violations: Violation[] = partitioned.violations;

package/src/public/operations/contracts.ts

@@ -569,6 +569,8 @@ const BASE_DATA_SCHEMAS: Readonly<
         "record_ontology_gap",
         "review_nonlogical",
         "replace_grounding",
+        "extend_requirement",
+        "keep_existing_grounding",
       ],
     },
     recommendedPredicateSchema: { type: ["object", "null"] },
@@ -584,7 +586,16 @@ const BASE_DATA_SCHEMAS: Readonly<
       description:
         "The planned predicate fact id (FACT-PRED-...) that a requires_predicate link must target. Candidate ids (SUGGEST-...) are never relationship targets.",
     },
-    existingGrounding: recordArray,
+    existingGrounding: {
+      ...recordArray,
+      description:
+        "The grounding links requirementId already has for this claim: matched by claim_key (the same proposition text) or, for a predicate fact, by the recommended candidate's canonical_key (the same predicate tuple in other words; matchedBy says which).",
+    },
+    decisionConflicts: {
+      ...recordArray,
+      description:
+        "When no hash-bound plan ran the contradiction analysis: stored decision facts of current requirements that agree with the complete candidate on its key arguments and decide the opposite (requirementId, factId, effect, proposedEffect, canonicalKey). A warning repeats each one.",
+    },
     replacementPlan: { type: ["object", "null"] },
     bindingHints: {
       ...recordArray,
@@ -648,6 +659,11 @@ const BASE_DATA_SCHEMAS: Readonly<
         relationships_created: integerValue,
         warnings: valueArray,
         semanticAdvisor: recordValue,
+        claimKey: {
+          ...stringValue,
+          description:
+            "For a fact with claim_text: the stored claim_key, derived from claim_text when the payload did not supply it.",
+        },
         status: stringValue,
         effectFailures: recordArray,
         nextActions: recordArray,
@@ -685,6 +701,22 @@ const BASE_DATA_SCHEMAS: Readonly<
     status: stringValue,
     effectFailures: recordArray,
     nextActions: recordArray,
+    outcome: {
+      type: "string",
+      enum: [
+        "plan_returned",
+        "supersession_required",
+        "plan_applied",
+        "dry_run",
+      ],
+      description:
+        "Absent on a direct delete. plan_returned: deletionPlan was returned and nothing was written; nextActions[0].input is the exact kb_apply_plan input. supersession_required: an authored requirement must be superseded with kb_upsert instead. plan_applied: approvedPlanHash matched and the plan was applied. dry_run: dryRun:true previewed the delete and nothing was written.",
+    },
+    dryRun: { const: true },
+    wouldDelete: recordValue,
+    planHash: stringValue,
+    sourcePaths: stringArray,
+    recoveryJournalId: stringValue,
   }),
   kb_check: {
     description:

package/src/public/operations/decision-firmness.ts

@@ -0,0 +1,280 @@
+/*
+ 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 path from "node:path";
+import {
+  MIN_WHY_CHANGED_WORDS,
+  WHY_THIS_CHANGED_HEADING,
+  carriesFirmness,
+  effectiveFirmness,
+  firmnessRef,
+  supersedeAcknowledgement,
+  whyThisChangedWords,
+} from "../../decision-firmness.js";
+import {
+  listLaneMarkdownFiles,
+  readText,
+} from "../../operations/migration/kb-sources.js";
+import { readAllShards } from "../../relationships/shards.js";
+import { readKbManifest } from "../../utils/kb-manifest.js";
+import type { Violation } from "../../utils/rule-registry.js";
+import {
+  type AuthoredEntity,
+  isCurrentAuthoredEntity,
+  readAuthoredEntity,
+} from "./entity-context.js";
+
+/** A firm decision must cite the human words it rests on (blocking). */
+// implements REQ-kb-decision-firmness
+export const DECISION_FIRM_UNREFERENCED_RULE = "decision-firm-unreferenced";
+/** Only a firm decision may supersede a firm decision (blocking). */
+// implements REQ-kb-decision-firmness
+export const DECISION_FIRM_SUPERSEDED_RULE = "decision-firm-superseded";
+/** A supersede must say why under "Why this changed" (blocking). */
+// implements REQ-kb-decision-firmness
+export const SUPERSEDES_REASON_MISSING_RULE = "supersedes-reason-missing";
+/** How many legacy supersedes the schema 9 migration acknowledged (info). */
+// implements REQ-kb-decision-firmness
+export const SUPERSEDES_REASON_ACKNOWLEDGED_RULE =
+  "supersedes-reason-acknowledged";
+
+// implements REQ-kb-decision-firmness
+export const DECISION_FIRMNESS_RULES = [
+  DECISION_FIRM_UNREFERENCED_RULE,
+  DECISION_FIRM_SUPERSEDED_RULE,
+  SUPERSEDES_REASON_MISSING_RULE,
+  SUPERSEDES_REASON_ACKNOWLEDGED_RULE,
+] as const;
+
+const DECISION_LANES = ["requirements", "adr"] as const;
+
+/** Every authored requirement and ADR. */
+// implements REQ-kb-decision-firmness
+export function listDecisionEntities(workspaceRoot: string): AuthoredEntity[] {
+  const entities: AuthoredEntity[] = [];
+  for (const file of listLaneMarkdownFiles(workspaceRoot, DECISION_LANES)) {
+    const content = readText(file.absolutePath);
+    if (content === null) continue;
+    const entity = readAuthoredEntity(content, file.relativePath);
+    if (entity !== null && carriesFirmness(entity.type)) entities.push(entity);
+  }
+  return entities;
+}
+
+/**
+ * Supersedes edges from requirements and ADRs, keyed by the superseding id,
+ * read from authored `links` and the relationship shards so the check and the
+ * migration agree before a sync. A shard edge whose source entity no longer
+ * exists is ignored: it must not make its target look replaced.
+ */
+// implements REQ-kb-decision-firmness
+export function authoredSupersedes(
+  workspaceRoot: string,
+  entities: readonly AuthoredEntity[],
+): Map<string, Set<string>> {
+  const edges = new Map<string, Set<string>>();
+  const known = new Set(entities.map((entity) => entity.id));
+  const add = (from: string, to: string) => {
+    const targets = edges.get(from) ?? new Set<string>();
+    targets.add(to);
+    edges.set(from, targets);
+  };
+  for (const entity of entities) {
+    const links = entity.data.links;
+    if (!Array.isArray(links)) continue;
+    for (const link of links) {
+      if (
+        link !== null &&
+        typeof link === "object" &&
+        (link as { type?: unknown }).type === "supersedes" &&
+        typeof (link as { target?: unknown }).target === "string"
+      ) {
+        add(entity.id, (link as { target: string }).target);
+      }
+    }
+  }
+  try {
+    for (const relationship of readAllShards(path.join(workspaceRoot, ".kb"))) {
+      if (relationship.type === "supersedes" && known.has(relationship.from))
+        add(relationship.from, relationship.to);
+    }
+  } catch {
+    // Malformed shards fail sync with their own diagnostic.
+  }
+  return edges;
+}
+
+function supersededIds(edges: ReadonlyMap<string, Set<string>>): Set<string> {
+  const superseded = new Set<string>();
+  for (const targets of edges.values())
+    for (const target of targets) superseded.add(target);
+  return superseded;
+}
+
+/**
+ * Superseding requirements and ADRs, whatever their status, without a "Why
+ * this changed" explanation. The schema 9 migration acknowledges their edges
+ * once, retired ones included, so one that becomes current again does not
+ * start blocking; read-only.
+ */
+// implements REQ-kb-decision-firmness
+export function unexplainedSupersedes(
+  entities: readonly AuthoredEntity[],
+  edges: ReadonlyMap<string, Set<string>>,
+): AuthoredEntity[] {
+  return entities
+    .filter(
+      (entity) =>
+        edges.has(entity.id) &&
+        whyThisChangedWords(entity.body) < MIN_WHY_CHANGED_WORDS,
+    )
+    .sort((left, right) => left.id.localeCompare(right.id));
+}
+
+/** The supersede edges of an entity, as the manifest acknowledges them. */
+// implements REQ-kb-decision-firmness
+export function supersedeAcknowledgements(
+  id: string,
+  edges: ReadonlyMap<string, Set<string>>,
+): string[] {
+  return [...(edges.get(id) ?? [])]
+    .sort()
+    .map((target) => supersedeAcknowledgement(id, target));
+}
+
+/** Evaluate the firmness rules over authored requirements and ADRs. */
+// implements REQ-kb-decision-firmness
+export function evaluateDecisionFirmness(
+  entities: readonly AuthoredEntity[],
+  edges: ReadonlyMap<string, Set<string>>,
+  rules: ReadonlySet<string> = new Set(DECISION_FIRMNESS_RULES),
+  acknowledged: ReadonlySet<string> = new Set(),
+): Violation[] {
+  const findings: Violation[] = [];
+  const superseded = supersededIds(edges);
+  const byId = new Map(entities.map((entity) => [entity.id, entity]));
+  const current = entities
+    .filter((entity) => isCurrentAuthoredEntity(entity, superseded))
+    .sort((left, right) => left.id.localeCompare(right.id));
+  const firmnessOf = (entity: AuthoredEntity) =>
+    effectiveFirmness(entity.type, entity.data.firmness);
+
+  if (rules.has(DECISION_FIRM_UNREFERENCED_RULE)) {
+    for (const entity of current) {
+      if (firmnessOf(entity) !== "firm") continue;
+      if (firmnessRef({ type: entity.type, ...entity.data }) !== undefined)
+        continue;
+      findings.push({
+        rule: DECISION_FIRM_UNREFERENCED_RULE,
+        entityId: entity.id,
+        description: `${entity.id} is marked firmness: firm but names no human words it rests on (origin.ref${entity.type === "req" ? " or approval_ref" : ""} is missing)`,
+        suggestion:
+          "Set origin.ref to the message, review or ticket where a human stated this rule; if no human stated it, use firmness: default (or exploratory for a guess)",
+        source: entity.path,
+        evidence: { type: entity.type, firmness: "firm" },
+      });
+    }
+  }
+
+  // Every superseder counts, retired ones too: replacing a non-firm
+  // superseder must not launder the overruled firm decision.
+  if (rules.has(DECISION_FIRM_SUPERSEDED_RULE)) {
+    for (const entity of [...entities].sort((left, right) =>
+      left.id.localeCompare(right.id),
+    )) {
+      if (firmnessOf(entity) === "firm") continue;
+      const firmTargets = [...(edges.get(entity.id) ?? [])]
+        .filter((id) => {
+          const target = byId.get(id);
+          return (
+            target !== undefined &&
+            effectiveFirmness(target.type, target.data.firmness) === "firm"
+          );
+        })
+        .sort();
+      if (firmTargets.length === 0) continue;
+      findings.push({
+        rule: DECISION_FIRM_SUPERSEDED_RULE,
+        entityId: entity.id,
+        description: `${entity.id} (firmness: ${firmnessOf(entity)}) supersedes the firm decision${firmTargets.length === 1 ? "" : "s"} ${firmTargets.join(", ")}; only a human may change a firm decision`,
+        suggestion:
+          "Ask the person who stated the firm decision; if they agree, mark the replacement firmness: firm with origin.ref to their words, otherwise remove the supersedes link and propose the change instead",
+        source: entity.path,
+        evidence: { firmness: firmnessOf(entity), firmTargets },
+      });
+    }
+  }
+
+  const currentIds = new Set(current.map((entity) => entity.id));
+  const unexplained = unexplainedSupersedes(entities, edges).filter((entity) =>
+    currentIds.has(entity.id),
+  );
+  const isAcknowledged = (entity: AuthoredEntity) =>
+    supersedeAcknowledgements(entity.id, edges).every((edge) =>
+      acknowledged.has(edge),
+    );
+  const exempt = unexplained.filter(isAcknowledged);
+  if (rules.has(SUPERSEDES_REASON_MISSING_RULE)) {
+    for (const entity of unexplained) {
+      if (isAcknowledged(entity)) continue;
+      const targets = [...(edges.get(entity.id) ?? [])].sort();
+      const unacknowledged = targets.filter(
+        (target) =>
+          !acknowledged.has(supersedeAcknowledgement(entity.id, target)),
+      );
+      findings.push({
+        rule: SUPERSEDES_REASON_MISSING_RULE,
+        entityId: entity.id,
+        description: `${entity.id} supersedes ${unacknowledged.join(", ")} without a '## ${WHY_THIS_CHANGED_HEADING}' section of at least ${MIN_WHY_CHANGED_WORDS} words`,
+        suggestion: `Add '## ${WHY_THIS_CHANGED_HEADING}' to the body: name the evidence (a failing test, a measured cost, a constraint the old decision missed, a new requirement) and answer the superseded decision's reasoning. A preference is not evidence; propose it instead of superseding.`,
+        source: entity.path,
+        evidence: { type: entity.type, supersedes: unacknowledged },
+      });
+    }
+  }
+  if (rules.has(SUPERSEDES_REASON_ACKNOWLEDGED_RULE) && exempt.length) {
+    findings.push({
+      rule: SUPERSEDES_REASON_ACKNOWLEDGED_RULE,
+      entityId: "workspace",
+      description: `${exempt.length} current superseding requirement${exempt.length === 1 ? " or ADR was" : "s and ADRs were"} recorded before schema 9 without a '${WHY_THIS_CHANGED_HEADING}' section`,
+      suggestion:
+        "When you next touch one, add the reason if the history or a person states it; never invent one",
+      evidence: {
+        total: exempt.length,
+        ids: exempt.slice(0, 25).map((entity) => entity.id),
+      },
+    });
+  }
+  return findings;
+}
+
+/** Read the authored decisions once and evaluate the selected rules. */
+// implements REQ-kb-decision-firmness
+export function collectDecisionFirmnessViolations(
+  rules: ReadonlySet<string>,
+  workspaceRoot: string,
+): Violation[] {
+  if (!DECISION_FIRMNESS_RULES.some((rule) => rules.has(rule))) return [];
+  const entities = listDecisionEntities(workspaceRoot);
+  return evaluateDecisionFirmness(
+    entities,
+    authoredSupersedes(workspaceRoot, entities),
+    rules,
+    new Set(readKbManifest(workspaceRoot)?.supersedesReasonAcknowledged ?? []),
+  );
+}

package/src/public/operations/discovery-executors.ts

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { compilerFingerprintReason } from "../../commands/sync/cache.js";
+import { effectiveFirmness } from "../../decision-firmness.js";
 import { EngineClient } from "../../engine.js";
 import {
   type IntentSearchAnalysis,
@@ -514,7 +515,13 @@ function factRowSummary(row: Record<string, unknown>): string {
     const names = Array.isArray(row.argumentNames)
       ? row.argumentNames.map(String).join(", ")
       : "";
-    return `${row.name}(${names})`;
+    // A built-in schema is no stored entity: its id is for kb_model's
+    // schemaId, not for a kb_query by id.
+    const builtin =
+      row.builtin === true
+        ? ` [builtin${id ? ` ${id}` : ""}, not a stored entity]`
+        : "";
+    return `${row.name}(${names})${builtin}`;
   }
   return `${id} (${String(row.title ?? "")})`;
 }
@@ -695,7 +702,15 @@ export async function executeQuery(
     const indexedPage = prolog.queryEntities
       ? await prolog.queryEntities(pageInput, signal)
       : await queryEntitiesViaQuery(prolog, pageInput, signal);
-    const paginated = indexedPage.entities;
+    // A requirement or ADR without authored firmness reads as `default`;
+    // the row says so, so a reader never has to know the default.
+    // implements REQ-kb-decision-firmness
+    const paginated = indexedPage.entities.map((entity) => {
+      const firmness = effectiveFirmness(entity.type, entity.firmness);
+      return firmness === undefined || entity.firmness === firmness
+        ? entity
+        : { ...entity, firmness };
+    });
     const text =
       indexedPage.count === 0
         ? `No entities found${type ? ` of type '${type}'` : ""}.`

package/src/public/operations/migration-plan.ts

@@ -750,7 +750,7 @@ export function buildActionsFromStatus(input: {
         invocation: legacyStorageBlocked
           ? {
               kind: "review",
-              instruction: `The legacy .kb/config.json still names knowledge files outside .kb/ and Kibi cannot move them: ${legacyStorage?.blockers.join(" ")} Keep one copy of each conflicting file (the .kb/ one is what Kibi compiles), remove or git-rm the legacy copy, then run 'kibi migrate --yes' to retire .kb/config.json.`,
+              instruction: `The legacy .kb/config.json still names knowledge files outside .kb/ and Kibi cannot move them: ${legacyStorage?.blockers.join(" ")} Compare each legacy copy with its .kb/ copy and keep the current one: replace the .kb/ copy when the legacy one is newer, or remove (git rm) the legacy copy when it is a stale duplicate. Then run 'kibi migrate --yes' to retire .kb/config.json.`,
             }
           : { kind: "cli", command_argv: ["kibi", "migrate", "--yes"] },
         affectedFiles: [

package/src/public/operations/specs/check-rules.generated.ts

@@ -55,6 +55,10 @@ export const SELECTABLE_RULE_NAMES: readonly string[] = [
   "predicate-schema-conformance",
   "entity-context-missing",
   "entity-context-acknowledged",
+  "decision-firm-unreferenced",
+  "decision-firm-superseded",
+  "supersedes-reason-missing",
+  "supersedes-reason-acknowledged",
   "policy-ownership",
   "policy-markers",
 ];
@@ -62,4 +66,4 @@ export const SELECTABLE_RULE_NAMES: readonly string[] = [
 // implements REQ-006
 /** Comma-separated "Allowed:" fragment for the kb_check rules description. */
 export const SELECTABLE_RULES_ALLOWED =
-  "must-priority-coverage, symbol-coverage, symbol-traceability, no-dangling-refs, source-relationship-parity, branch-store-not-compiled, source-path-dangling, no-cycles, required-fields, deprecated-adr-no-successor, superseded-requirement-open, scenario-feasibility, scenario-feasibility-unknown, exception-claim-keys, numeric-string-value, rule-key-arguments-missing, domain-contradictions, logic-coverage, rule-safety, rule-verifiability, query-plan-safety, req-status-vocabulary, strict-fact-shape, strict-req-fact-pairing, predicate-verifiability, strict-readiness, semantic-completeness, related-requirement-unmodeled, proof-contract-symbols, entity-id-style, domain-redundancy, domain-implication, subject-key-identity, subject-key-shape, ontology-quality, exception-unapproved, exception-approval-self-attested, agent-requirement-unapproved, requirement-rationale-missing, symbol-owner-superseded, adr-unlinked, adr-proposed, predicate-schema-conformance, entity-context-missing, entity-context-acknowledged, policy-ownership, policy-markers";
+  "must-priority-coverage, symbol-coverage, symbol-traceability, no-dangling-refs, source-relationship-parity, branch-store-not-compiled, source-path-dangling, no-cycles, required-fields, deprecated-adr-no-successor, superseded-requirement-open, scenario-feasibility, scenario-feasibility-unknown, exception-claim-keys, numeric-string-value, rule-key-arguments-missing, domain-contradictions, logic-coverage, rule-safety, rule-verifiability, query-plan-safety, req-status-vocabulary, strict-fact-shape, strict-req-fact-pairing, predicate-verifiability, strict-readiness, semantic-completeness, related-requirement-unmodeled, proof-contract-symbols, entity-id-style, domain-redundancy, domain-implication, subject-key-identity, subject-key-shape, ontology-quality, exception-unapproved, exception-approval-self-attested, agent-requirement-unapproved, requirement-rationale-missing, symbol-owner-superseded, adr-unlinked, adr-proposed, predicate-schema-conformance, entity-context-missing, entity-context-acknowledged, decision-firm-unreferenced, decision-firm-superseded, supersedes-reason-missing, supersedes-reason-acknowledged, policy-ownership, policy-markers";

package/src/public/operations/specs/mutation-schemas.ts

@@ -125,6 +125,12 @@ export const ENTITY_PROPERTIES_SCHEMA = {
       description:
         "Requirement-only. Optional reference to the exception's approval decision record.",
     },
+    firmness: {
+      type: "string",
+      enum: ["firm", "default", "exploratory"],
+      description:
+        "req/adr only. firm = a human stated it as a rule (needs origin.ref to their words); default (when absent) = delegated or agent choice; exploratory = flagged guess.",
+    },
     rationale: {
       type: "string",
       minLength: 1,

package/src/public/operations/specs/mutation.ts

@@ -39,7 +39,7 @@ export const deleteSpec = {
   name: "kb_delete",
   cliName: "delete",
   description:
-    "Delete entities by ID. Use only for intentional removals after dependency checks. Do not use as a bulk cleanup shortcut. Side effects: mutates and saves KB; skips entities with dependents.",
+    "Delete entities by ID, or exact relationship triples. Use only for intentional removals after dependency checks. Do not use as a bulk cleanup shortcut. An entity authored in a Markdown or YAML source is not deleted directly: the call writes nothing and returns outcome plan_returned with a hash-bound deletionPlan and a nextActions entry holding the exact kb_apply_plan input ({plan, approvedPlanHash}); apply that unmodified, or repeat this call with approvedPlanHash = deletionPlan.planHash to apply the freshly computed plan in one step (a stale or different hash fails with DELETE_PLAN_HASH_MISMATCH and writes nothing). Authored requirements are never deleted: outcome supersession_required points to kb_upsert with a supersedes relationship. dryRun:true previews any delete and writes nothing. Side effects: mutates and saves KB and authored sources; skips entities with dependents; dryRun and plan_returned write nothing.",
   businessInputSchema: {
     type: "object",
     oneOf: [
@@ -73,7 +73,12 @@ export const deleteSpec = {
         type: "string",
         pattern: "^[a-fA-F0-9]{64}$",
         description:
-          "Exact hash returned by a prior authored-entity deletion plan.",
+          "With ids only: the deletionPlan.planHash a prior call for the same ids returned. The plan is recomputed and applied through kb_apply_plan when its hash still matches; a mismatch fails with DELETE_PLAN_HASH_MISMATCH and writes nothing. Not allowed with relationships or dryRun.",
+      },
+      dryRun: {
+        type: "boolean",
+        description:
+          "Preview without writing. Relationship and direct entity deletes run their preflight and return outcome dry_run with wouldDelete counts, the sourceWrites (paths and hashes) a commit would make, and skippedEffects. Authored ids return the same deletion plan as without dryRun.",
       },
     },
   },