kibi-cli 2.21.0 → 2.22.0

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,
@@ -94,6 +95,8 @@ export type QueryPayload = {
   readonly entities: readonly Record<string, unknown>[];
   readonly count: number;
   readonly factQuery?: FactQueryPayload;
+  /** Present when an empty answer came from a store never compiled for this branch. */
+  readonly branchStore?: SearchBranchStoreNotice;
 };
 
 export const FACT_KINDS = [
@@ -514,7 +517,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,10 +704,22 @@ 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 };
+    });
+    // An empty page from a never-compiled store says nothing about the
+    // authored entities, so the answer names the store state.
+    const storeNotice =
+      indexedPage.count === 0 ? uncompiledSearchNotice(context) : null;
     const text =
       indexedPage.count === 0
-        ? `No entities found${type ? ` of type '${type}'` : ""}.`
+        ? `No entities found${type ? ` of type '${type}'` : ""}.${storeNotice ? ` Note: ${storeNotice.detail} Run kibi sync before relying on query results.` : ""}`
         : `Found ${indexedPage.count} entities${type ? ` of type '${type}'` : ""}. Showing ${paginated.length} (offset ${offset}, limit ${limit}): ${paginated
             .map((entity) => {
               const entityId = String(entity.id ?? "").replace(
@@ -710,7 +731,11 @@ export async function executeQuery(
             .join(", ")}`;
     return {
       content: [{ type: "text", text }],
-      structuredContent: { entities: paginated, count: indexedPage.count },
+      structuredContent: {
+        entities: paginated,
+        count: indexedPage.count,
+        ...(storeNotice ? { branchStore: storeNotice } : {}),
+      },
     };
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);

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

@@ -396,6 +396,66 @@ function predicateSchemaAlignmentAction(
 /** Migration code for mechanical predicate namespace/alias repairs. */
 export const PREDICATE_SCHEMA_ALIGNMENT_CODE = "predicate_schema_alignment";
 
+/** Migration code of the grouped untracked-source parity findings. */
+export const UNTRACKED_KNOWLEDGE_SOURCES_CODE = "untracked_knowledge_sources";
+
+/**
+ * Every source-relationship-parity finding explained by untracked files
+ * (evidence `untrackedSources`) has one cause and one fix: the files Git
+ * does not track and no pending-source receipt covers. After a storage move
+ * that can be thousands of relationships, so they become one review action
+ * naming the files instead of one per relationship.
+ */
+// implements REQ-agent-guided-migration-orchestration, REQ-kibi-source-relationship-parity
+function untrackedSourceActionFromViolations(
+  violations: readonly Readonly<Record<string, unknown>>[],
+): { action: MigrationAction; consumed: ReadonlySet<number> } | null {
+  const consumed = new Set<number>();
+  const files = new Set<string>();
+  const entityIds = new Set<string>();
+  const relationships: unknown[] = [];
+  for (const [index, violation] of violations.entries()) {
+    if (violation.rule !== "source-relationship-parity") continue;
+    const evidence = isRecord(violation.evidence) ? violation.evidence : {};
+    const sources = Array.isArray(evidence.untrackedSources)
+      ? evidence.untrackedSources.filter(isRecord)
+      : [];
+    if (sources.length === 0) continue;
+    consumed.add(index);
+    for (const source of sources) {
+      if (typeof source.file === "string") files.add(source.file);
+      if (typeof source.entityId === "string") entityIds.add(source.entityId);
+    }
+    if (evidence.relationship !== undefined)
+      relationships.push(evidence.relationship);
+  }
+  if (consumed.size === 0) return null;
+  const listed = [...files].sort();
+  return {
+    consumed,
+    action: migrationAction({
+      id: "untracked-knowledge-sources",
+      code: UNTRACKED_KNOWLEDGE_SOURCES_CODE,
+      category: "relationship",
+      safety: "review",
+      invocation: {
+        kind: "review",
+        instruction: `${consumed.size} authored relationship(s) are missing from the compiled KB because ${listed.length} file(s) declaring their endpoints are not tracked by Git and no pending-source receipt covers them: ${listed.join(", ")}. Stage them (git add; staging is enough, Kibi never stages files itself) or rewrite the entities with kb_upsert, then run kibi sync and rerun kibi migrate.`,
+      },
+      affectedEntityIds: [...entityIds],
+      affectedFiles: listed,
+      postconditions: [{ rule: "source-relationship-parity", findings: 0 }],
+      evidence: {
+        relationshipCount: consumed.size,
+        files: listed,
+        // A sample; the count above is the full number.
+        relationships: relationships.slice(0, 20),
+      },
+      dispositionRequired: true,
+    }),
+  };
+}
+
 // implements REQ-agent-guided-migration-orchestration, REQ-kibi-predicate-vocabulary-migration, REQ-cli-schema-migration
 export function buildActionsFromCheck(input: {
   violations?: readonly Readonly<Record<string, unknown>>[];
@@ -404,8 +464,11 @@ export function buildActionsFromCheck(input: {
   const actions: MigrationAction[] = [];
   const lifecycle = lifecycleActionsFromViolations(input.violations ?? []);
   actions.push(...lifecycle.actions.map(migrationAction));
+  const untracked = untrackedSourceActionFromViolations(input.violations ?? []);
+  if (untracked !== null) actions.push(untracked.action);
   for (const [index, violation] of (input.violations ?? []).entries()) {
     if (lifecycle.consumed.has(index)) continue;
+    if (untracked?.consumed.has(index)) continue;
     const rule = typeof violation.rule === "string" ? violation.rule : "check";
     const entityId =
       typeof violation.entityId === "string" ? violation.entityId : "";
@@ -621,6 +684,18 @@ function readLegacySchemaVersion(
 /** Migration action code of the automatic recompile of changed sources. */
 export const FRESHNESS_RESYNC = "freshness_resync";
 
+// implements REQ-cli-status-pre-first-sync
+/**
+ * Stale reasons one `kibi sync` clears: sources whose content changed since
+ * the last compilation, and a store compiled under another compiler contract
+ * (the sync discards that cache, re-imports every source and stamps the
+ * current contract).
+ */
+const RESYNC_REASON_CODES: ReadonlySet<string> = new Set([
+  ...MTIME_SOURCE_REASON_CODES,
+  "compiler_changed",
+]);
+
 export function buildActionsFromStatus(input: {
   workspaceRoot: string;
   branchAttachment?: Readonly<Record<string, unknown>>;
@@ -686,17 +761,20 @@ export function buildActionsFromStatus(input: {
   }
 
   const storeState = typeof store?.state === "string" ? store.state : null;
-  const legacyStorageMigrationRequired = legacyConfigExists(
-    input.workspaceRoot,
-  );
+  // Legacy storage is evaluated whether or not the legacy config survives:
+  // legacy copies left beside a migrated .kb/ (moved, identical or stale)
+  // are the same finding 'kibi doctor' and 'kibi migrate' report.
+  // implements REQ-cli-schema-migration
+  const legacyStorage = planLegacyStorageMigration(input.workspaceRoot);
+  const legacyStorageMigrationRequired =
+    legacyConfigExists(input.workspaceRoot) ||
+    legacyStorage.moves.length > 0 ||
+    legacyStorage.removals.length > 0 ||
+    legacyStorage.blockers.length > 0;
   // 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;
+  const legacyStorageBlocked = legacyStorage.blockers.length > 0;
   if (storeState === "missing") {
     actions.push(
       migrationAction({
@@ -750,26 +828,29 @@ 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: `Legacy knowledge files outside .kb/ cannot be migrated automatically: ${legacyStorage.blockers.join(" ")} Then run 'kibi migrate --yes'.`,
             }
           : { kind: "cli", command_argv: ["kibi", "migrate", "--yes"] },
         affectedFiles: [
           ".kb/manifest.json",
           ".kb/migrations",
           ".kb/config.json",
-          ...(legacyStorage?.moves.map((move) => move.from) ?? []),
+          ...legacyStorage.moves.map((move) => move.from),
+          ...legacyStorage.removals.map((removal) => removal.path),
         ],
         evidence: {
           configStatus,
-          ...(legacyStorage === null
-            ? {}
-            : {
+          ...(legacyStorageMigrationRequired
+            ? {
                 legacyStorage: {
                   moves: legacyStorage.moves,
+                  removals: legacyStorage.removals,
+                  conflicts: legacyStorage.conflicts,
                   blockers: legacyStorage.blockers,
                   legacyConfig: legacyStorage.legacyConfig,
                 },
-              }),
+              }
+            : {}),
         },
         dependsOn: storeState === "missing" ? ["branch-store-ensure"] : [],
         autoApplicable: !operatorOnly,
@@ -816,12 +897,12 @@ export function buildActionsFromStatus(input: {
   // implements REQ-cli-status-pre-first-sync
   // Sources whose content changed since the last compilation (kb_status has
   // already dropped mtime-only reasons) are fixed by recompiling them: one
-  // automatic `kibi sync`, not a review per file. An uncompiled store is
-  // compiled by the step above, which also covers these files.
+  // automatic `kibi sync`, not a review per file. A store compiled under
+  // another compiler contract is fixed by the same sync. An uncompiled store
+  // is compiled by the step above, which also covers these reasons.
   const resyncReasons = (input.staleReasons ?? []).filter(
     (reason) =>
-      typeof reason.code === "string" &&
-      MTIME_SOURCE_REASON_CODES.has(reason.code),
+      typeof reason.code === "string" && RESYNC_REASON_CODES.has(reason.code),
   );
   if (resyncReasons.length > 0 && uncompiled === undefined) {
     actions.push(
@@ -856,7 +937,7 @@ export function buildActionsFromStatus(input: {
     // Planned above as an automatic compile step, not a review.
     if (code === BRANCH_STORE_NOT_COMPILED) continue;
     // Planned above as one automatic resync (or covered by the compile).
-    if (MTIME_SOURCE_REASON_CODES.has(code)) continue;
+    if (RESYNC_REASON_CODES.has(code)) continue;
     const file = typeof reason.path === "string" ? reason.path : "";
     actions.push(
       migrationAction({

package/src/public/operations/result-envelope.ts

@@ -17,6 +17,36 @@ function diagnostics(value: unknown): KibiResult["diagnostics"] {
   });
 }
 
+// Discovery operations whose empty answer may come from an uncompiled store.
+const STORE_READ_OPERATIONS = new Set(["kb_search", "kb_query"]);
+
+/**
+ * A search or query answered from a branch store that was never compiled
+ * reads an empty KB. The payload already names the store state; the envelope
+ * also raises it as a warning, so a caller that reads only `status` and
+ * `diagnostics` does not take the empty answer as "nothing governs this".
+ */
+// implements REQ-cli-status-pre-first-sync, REQ-mcp-search-discovery
+function uncompiledStoreDiagnostics(
+  operation: string,
+  row: Record<string, unknown> | undefined,
+): KibiResult["diagnostics"] {
+  const store = row?.branchStore;
+  if (
+    !STORE_READ_OPERATIONS.has(operation) ||
+    !record(store) ||
+    store.state !== "not_compiled"
+  )
+    return [];
+  return [
+    {
+      ...(typeof store.code === "string" ? { code: store.code } : {}),
+      severity: "warning",
+      message: `${typeof store.detail === "string" ? `${store.detail} ` : ""}An empty answer here does not mean no requirement governs this; run \`kibi sync\` and ask again.`,
+    },
+  ];
+}
+
 function nextActions(value: unknown): KibiResult["nextActions"] {
   if (!Array.isArray(value)) return [];
   return value.flatMap((entry) => {
@@ -214,7 +244,10 @@ export function toKibiResult<T>(
       ...spec.effects.map((effect) => effectStatus(effect, row, outcome)),
       ...extraFailedEffects(spec.effects, row),
     ],
-    diagnostics: options.diagnostics ?? diagnostics(row?.diagnostics),
+    diagnostics: options.diagnostics ?? [
+      ...diagnostics(row?.diagnostics),
+      ...uncompiledStoreDiagnostics(String(spec.name), row),
+    ],
     nextActions: options.nextActions ?? nextActions(row?.nextActions),
     ...(resultError ? { error: resultError } : {}),
   };

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

@@ -13,6 +13,7 @@ export const SELECTABLE_RULE_NAMES: readonly string[] = [
   "must-priority-coverage",
   "symbol-coverage",
   "symbol-traceability",
+  "symbol-granularity",
   "no-dangling-refs",
   "source-relationship-parity",
   "branch-store-not-compiled",
@@ -55,6 +56,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 +67,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, symbol-granularity, 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.",
       },
     },
   },

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

@@ -236,13 +236,13 @@ export const applyPlanSpec = {
         type: "object",
         required: ["version", "planHash"],
         description:
-          "The complete kibi.bootstrap-plan.v1, kibi.compile-plan.v1, kibi.migration-plan.v2, or hash-bound kibi.entity-deletion-plan.v1 object. Migration plans require approvedActionIds and reject blocked/non-automatic actions.",
+          "The complete kibi.bootstrap-plan.v1, kibi.compile-plan.v1, kibi.migration-plan.v2, or hash-bound kibi.entity-deletion-plan.v1 object. Migration plans require approvedActionIds and reject blocked actions and review actions Kibi cannot execute.",
       },
       approvedActionIds: {
         type: "array",
         items: { type: "string", minLength: 1 },
         description:
-          "Required for migration-plan.v2. Exact automatic action IDs explicitly approved for this application.",
+          "Required for migration-plan.v2. Exact action IDs explicitly approved for this application: automatic actions, or review actions with a cli invocation that Kibi executes only when approved by id (for example semantic_inventory_rederive_drop_grounding).",
       },
       recoveryJournalId: {
         type: "string",