kibi-cli 2.20.0 → 2.21.2

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

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 import * as path from "node:path";
+import { planLegacyStorageMigration } from "../../commands/legacy-storage-migration.js";
 import { BRANCH_STORE_NOT_COMPILED } from "../../utils/branch-store.js";
 import { legacyConfigExists } from "../../utils/config.js";
 import { MTIME_SOURCE_REASON_CODES } from "../../utils/content-freshness.js";
@@ -688,6 +689,14 @@ export function buildActionsFromStatus(input: {
   const legacyStorageMigrationRequired = legacyConfigExists(
     input.workspaceRoot,
   );
+  // A legacy cutover that cannot move its files (a destination already
+  // exists, a malformed config) is an operator decision, not an automatic
+  // step that fails when applied and takes the compile with it.
+  const legacyStorage = legacyStorageMigrationRequired
+    ? planLegacyStorageMigration(input.workspaceRoot)
+    : null;
+  const legacyStorageBlocked =
+    legacyStorage !== null && legacyStorage.blockers.length > 0;
   if (storeState === "missing") {
     actions.push(
       migrationAction({
@@ -724,6 +733,8 @@ export function buildActionsFromStatus(input: {
   }
 
   if (configStatus.needsMigration || legacyStorageMigrationRequired) {
+    const operatorOnly =
+      configStatus.status === "newer" || legacyStorageBlocked;
     actions.push(
       migrationAction({
         id: "schema-config-upgrade",
@@ -734,17 +745,34 @@ export function buildActionsFromStatus(input: {
               ? "legacy_storage_migration"
               : "schema_version_upgrade",
         category: "schema",
-        state: configStatus.status === "newer" ? "blocked" : "ready",
-        safety: configStatus.status === "newer" ? "operator" : "automatic",
-        invocation: { kind: "cli", command_argv: ["kibi", "migrate", "--yes"] },
+        state: operatorOnly ? "blocked" : "ready",
+        safety: operatorOnly ? "operator" : "automatic",
+        invocation: legacyStorageBlocked
+          ? {
+              kind: "review",
+              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: [
           ".kb/manifest.json",
           ".kb/migrations",
           ".kb/config.json",
+          ...(legacyStorage?.moves.map((move) => move.from) ?? []),
         ],
-        evidence: { configStatus },
+        evidence: {
+          configStatus,
+          ...(legacyStorage === null
+            ? {}
+            : {
+                legacyStorage: {
+                  moves: legacyStorage.moves,
+                  blockers: legacyStorage.blockers,
+                  legacyConfig: legacyStorage.legacyConfig,
+                },
+              }),
+        },
         dependsOn: storeState === "missing" ? ["branch-store-ensure"] : [],
-        autoApplicable: configStatus.status !== "newer",
+        autoApplicable: !operatorOnly,
       }),
     );
   }
@@ -769,12 +797,16 @@ export function buildActionsFromStatus(input: {
           typeof store?.path === "string" ? store.path : ".kb/branches",
         ],
         evidence: { reason: uncompiled },
+        // A blocked schema step waits on an operator; the compile still runs
+        // from the .kb/ sources Kibi already reads.
         dependsOn: actions
-          .map((action) => action.id)
           .filter(
-            (id) =>
-              id === "branch-store-ensure" || id === "schema-config-upgrade",
-          ),
+            (action) =>
+              action.state === "ready" &&
+              (action.id === "branch-store-ensure" ||
+                action.id === "schema-config-upgrade"),
+          )
+          .map((action) => action.id),
         postconditions: [{ branchStore: "compiled" }],
         autoApplicable: true,
       }),

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

@@ -19,22 +19,13 @@ export const ENTITY_TYPES = [
   "fact",
 ] as const;
 
-// An observation or meta fact may quote a claim in claim_text alone: it is a
-// non-grounding review note, so it does not claim the clause's key.
+// A claim_key names the clause in claim_text, so it never travels alone. The
+// reverse is open: Kibi derives a missing claim_key from claim_text on a
+// grounding fact, and an observation or meta fact quotes a claim without one.
+// implements REQ-kibi-review-observation-claim-text-v2
 const CLAIM_PROVENANCE_CONDITIONAL = JSON.parse(`{
-  "if": {
-    "anyOf": [
-      { "required": ["claim_key"] },
-      {
-        "required": ["claim_text"],
-        "not": {
-          "properties": { "fact_kind": { "enum": ["observation", "meta"] } },
-          "required": ["fact_kind"]
-        }
-      }
-    ]
-  },
-  "then": { "required": ["claim_key", "claim_text"] }
+  "if": { "required": ["claim_key"] },
+  "then": { "required": ["claim_text"] }
 }`) as Record<string, unknown>;
 
 export const ENTITY_PROPERTIES_SCHEMA = {
@@ -134,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,
@@ -293,12 +290,12 @@ export const ENTITY_PROPERTIES_SCHEMA = {
       type: "string",
       pattern: "^CLAIM-[A-F0-9]{16}$",
       description:
-        "Stable semantic-advisor key for the atomic prose clause grounded by this fact.",
+        "Stable key of the atomic prose clause grounded by this fact, derived from claim_text. Optional: when omitted, Kibi derives it; when sent, it must equal the derived key.",
     },
     claim_text: {
       type: "string",
       description:
-        "Exact atomic requirement clause represented by this fact, retained for human audit. Requires claim_key, except on an observation or meta fact, which may quote the clause it is about without claim_key.",
+        "Exact atomic requirement clause represented by this fact, retained for human audit. On a grounding fact Kibi derives claim_key from it; an observation or meta fact quotes the clause it is about without a key.",
     },
     predicate_name: {
       type: "string",

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.",
       },
     },
   },

package/src/public/schemas/entity.ts

@@ -42,19 +42,8 @@ type VerificationPerspective = "internal" | "consumer";
 
 const factConditionals = JSON.parse(`[
   {
-    "if": {
-      "anyOf": [
-        { "required": ["claim_key"] },
-        {
-          "required": ["claim_text"],
-          "not": {
-            "properties": { "fact_kind": { "enum": ["observation", "meta"] } },
-            "required": ["fact_kind"]
-          }
-        }
-      ]
-    },
-    "then": { "required": ["claim_key", "claim_text"] }
+    "if": { "required": ["claim_key"] },
+    "then": { "required": ["claim_text"] }
   },
   {
     "if": {
@@ -369,6 +358,12 @@ const entitySchema: Record<string, unknown> = {
     text_ref: { type: "string" },
     // Provenance of any authored entity: who wrote it and on what authority.
     origin: ENTITY_ORIGIN_SCHEMA,
+    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: ["success", "rejection", "error"],
@@ -724,6 +719,12 @@ const entitySchema: Record<string, unknown> = {
         },
       },
     },
+    {
+      if: {
+        properties: { type: { enum: ["req", "adr"] } },
+      },
+      else: { not: { required: ["firmness"] } },
+    },
     {
       if: {
         properties: { type: { const: "scenario" } },

package/src/public/skills/kibi-traceability/SKILL.md

@@ -43,10 +43,12 @@ sequential `kb_upsert`, then run final check and coverage. Kibi authors tracked
 files transactionally but never Git-stages or commits them. Do not read or edit
 `.kb` directly.
 
-Use `kb_delete` only for intentional cleanup. Authored entity deletion returns a
-hash-bound approval plan; requirements normally evolve through a new
-requirement linked with `supersedes`. Relationship deletes patch shards while
-preserving unrelated records.
+Use `kb_delete` only for intentional cleanup; `dryRun: true` previews any
+delete without writing. Authored entity deletion returns `outcome:
+plan_returned` with a hash-bound plan whose `nextActions[0].input` is the exact
+`kb_apply_plan` input; requirements return `supersession_required` and evolve
+through a new requirement linked with `supersedes`. Relationship deletes patch
+shards while preserving unrelated records.
 
 ## Typed recovery and proof