kibi-cli 2.21.2 → 2.22.1

package/src/public/impact/diagnostics.ts

@@ -12,6 +12,7 @@ import {
   getNonBehavioralSymbolNames,
   isAllowedGranularityReason,
   isTraceabilityRelationshipType,
+  narrowerSymbols,
 } from "../symbol-granularity.js";
 import type {
   QualityDiagnostic,
@@ -19,16 +20,6 @@ import type {
   SymbolGranularityDiagnosticsOptions,
 } from "./types.js";
 
-function isNarrowerSymbol(
-  manifestSymbolName: string,
-  candidate: ExtractedSymbol,
-  sourceSymbols: readonly ExtractedSymbol[],
-): boolean {
-  if (candidate.name === manifestSymbolName) return false;
-  if (candidate.name.startsWith(`${manifestSymbolName}.`)) return true;
-  return !sourceSymbols.some((symbol) => symbol.name === manifestSymbolName);
-}
-
 function hasTraceabilityRelationship(result: ExtractionResult): boolean {
   return result.relationships.some((relationship) =>
     isTraceabilityRelationshipType(relationship.type),
@@ -110,6 +101,7 @@ function isChangedBehavioralReviewCandidate(symbol: ExtractedSymbol): boolean {
   return symbol.hunkRanges.length > 0;
 }
 
+// implements REQ-cli-staged-impact-enforcement, REQ-cli-check
 export function createSymbolGranularityDiagnostics(
   options: SymbolGranularityDiagnosticsOptions,
 ): KibiImpactDiagnostic[] {
@@ -130,15 +122,17 @@ export function createSymbolGranularityDiagnostics(
       result.sourceFile,
       options,
     );
-    const narrowerSymbols = candidateSymbols.filter((symbol) =>
-      isNarrowerSymbol(result.entity.title, symbol, sourceSymbols),
+    const narrower = narrowerSymbols(
+      result.entity.title,
+      candidateSymbols,
+      sourceSymbols,
     );
-    if (narrowerSymbols.length === 0) continue;
+    if (narrower.length === 0) continue;
 
-    const behavioralNames = getBehavioralSymbolNames(narrowerSymbols);
+    const behavioralNames = getBehavioralSymbolNames(narrower);
     if (behavioralNames.length === 0) continue;
 
-    const nonBehavioralNames = getNonBehavioralSymbolNames(narrowerSymbols);
+    const nonBehavioralNames = getNonBehavioralSymbolNames(narrower);
     const ignoredSymbolsSuggestion =
       nonBehavioralNames.length > 0
         ? ` Non-behavioral symbols ignored for this decision: ${nonBehavioralNames.join(
@@ -146,15 +140,33 @@ export function createSymbolGranularityDiagnostics(
           )}.`
         : "";
 
+    // A title the extractor does not produce (a private class member, a
+    // renamed or removed declaration) can never become granular by refresh:
+    // say so instead of only calling the link coarse.
+    const titleExtracted = sourceSymbols.some(
+      (symbol) => symbol.name === result.entity.title,
+    );
     diagnostics.push({
       id: "symbol_granularity_violation",
       severity: "error",
       blocking: true,
       category: "symbol",
+      entityId: result.entity.id,
+      ...(result.entity.source ? { source: result.entity.source } : {}),
       files: [result.entity.source, result.sourceFile],
       docs: ["docs/symbol-traceability-taxonomy.md"],
-      message: `Symbol ${result.entity.id} links ${result.sourceFile} coarsely while granular symbols are available (behavioral only): ${behavioralNames.join(", ")}`,
-      suggestion: `Move ownership/coverage/test relationships to the narrow behavioral symbol, add a manifest behavioral anchor, or add granularity_reason with ${ALLOWED_GRANULARITY_REASONS_PROSE} when the coarse symbol is intentional.${ignoredSymbolsSuggestion}`,
+      message: titleExtracted
+        ? `Symbol ${result.entity.id} links ${result.sourceFile} coarsely while granular symbols are available (behavioral only): ${behavioralNames.join(", ")}`
+        : `Symbol ${result.entity.id} names '${result.entity.title}', which the source extractor does not produce for ${result.sourceFile} (private class members and removed or renamed declarations are not tracked), so it links ${result.sourceFile} coarsely while granular symbols are available (behavioral only): ${behavioralNames.join(", ")}`,
+      suggestion: titleExtracted
+        ? `Move ownership/coverage/test relationships to the narrow behavioral symbol, add a manifest behavioral anchor, or add granularity_reason with ${ALLOWED_GRANULARITY_REASONS_PROSE} when the coarse symbol is intentional.${ignoredSymbolsSuggestion}`
+        : `Re-point this symbol's relationships to the public declaration that owns the behavior (one of: ${behavioralNames.join(", ")}) or remove the symbol; add granularity_reason with ${ALLOWED_GRANULARITY_REASONS_PROSE} only when coarse ownership is intentional.${ignoredSymbolsSuggestion}`,
+      evidence: {
+        sourceFile: result.sourceFile,
+        title: result.entity.title,
+        titleExtracted,
+        granularSymbols: behavioralNames,
+      },
     });
   }
 

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

@@ -57,6 +57,7 @@ import {
   collectSourcePathDanglingViolations,
 } from "./source-path-dangling.js";
 import { collectSourceRelationshipParityViolations } from "./source-relationship-parity.js";
+import { collectSymbolGranularityViolations } from "./symbol-granularity-check.js";
 import type { OperationResult } from "./types.js";
 import { readWorkspaceSnapshot } from "./workspace-snapshot.js";
 
@@ -367,6 +368,11 @@ export async function executeCheck(
     const sourcePathFindings = rulesAllowlist.has(SOURCE_PATH_DANGLING_RULE)
       ? collectSourcePathDanglingViolations(workspaceRoot)
       : [];
+    const symbolGranularityFindings = await collectSymbolGranularityViolations(
+      prolog,
+      workspaceRoot,
+      rulesAllowlist,
+    );
     const originReviewFindings = await collectOriginReviewViolations(
       prolog,
       rulesAllowlist,
@@ -390,6 +396,7 @@ export async function executeCheck(
       ...queryPlanViolations,
       ...sourceRelationshipParityViolations,
       ...sourcePathFindings,
+      ...symbolGranularityFindings,
       ...predicateConformanceFindings,
       ...originReviewFindings,
       ...entityContextFindings,

package/src/public/operations/contracts.ts

@@ -442,7 +442,12 @@ const BASE_DATA_SCHEMAS: Readonly<
   }),
   kb_skills_read: objectData({ content: stringValue }, ["content"]),
   kb_query: objectData(
-    { entities: recordArray, count: integerValue, factQuery: recordValue },
+    {
+      entities: recordArray,
+      count: integerValue,
+      factQuery: recordValue,
+      branchStore: recordValue,
+    },
     ["entities", "count"],
   ),
   kb_search: objectData(

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

@@ -63,6 +63,16 @@ export const DECISION_FIRMNESS_RULES = [
 
 const DECISION_LANES = ["requirements", "adr"] as const;
 
+/** The schema version from which a supersede must explain itself. */
+const SUPERSEDES_REASON_SCHEMA_VERSION = 9;
+
+/**
+ * Told on a KB older than schema 9: the pending schema upgrade acknowledges
+ * supersedes recorded before the rule existed, so no edit is required now.
+ */
+const PRE_SCHEMA9_SUPERSEDES_NOTE =
+  " Supersedes recorded before schema 9 are acknowledged by the plan's schema-config-upgrade (kibi migrate --yes); add the reason only when you next touch the requirement.";
+
 /** Every authored requirement and ADR. */
 // implements REQ-kb-decision-firmness
 export function listDecisionEntities(workspaceRoot: string): AuthoredEntity[] {
@@ -164,7 +174,11 @@ export function evaluateDecisionFirmness(
   edges: ReadonlyMap<string, Set<string>>,
   rules: ReadonlySet<string> = new Set(DECISION_FIRMNESS_RULES),
   acknowledged: ReadonlySet<string> = new Set(),
+  options: Readonly<{ schemaVersion?: number | null }> = {},
 ): Violation[] {
+  const preSchema9 =
+    typeof options.schemaVersion === "number" &&
+    options.schemaVersion < SUPERSEDES_REASON_SCHEMA_VERSION;
   const findings: Violation[] = [];
   const superseded = supersededIds(edges);
   const byId = new Map(entities.map((entity) => [entity.id, entity]));
@@ -241,7 +255,7 @@ export function evaluateDecisionFirmness(
         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.`,
+        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.${preSchema9 ? PRE_SCHEMA9_SUPERSEDES_NOTE : ""}`,
         source: entity.path,
         evidence: { type: entity.type, supersedes: unacknowledged },
       });
@@ -271,10 +285,12 @@ export function collectDecisionFirmnessViolations(
 ): Violation[] {
   if (!DECISION_FIRMNESS_RULES.some((rule) => rules.has(rule))) return [];
   const entities = listDecisionEntities(workspaceRoot);
+  const manifest = readKbManifest(workspaceRoot);
   return evaluateDecisionFirmness(
     entities,
     authoredSupersedes(workspaceRoot, entities),
     rules,
-    new Set(readKbManifest(workspaceRoot)?.supersedesReasonAcknowledged ?? []),
+    new Set(manifest?.supersedesReasonAcknowledged ?? []),
+    { schemaVersion: manifest?.schemaVersion ?? null },
   );
 }

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

@@ -95,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 = [
@@ -711,9 +713,13 @@ export async function executeQuery(
         ? 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(
@@ -725,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);
@@ -1111,6 +1121,13 @@ export async function executeStatus(
         : { proofSnapshotError: snapshotEvidence.error }),
     };
     const schemaStatus = readMigrationConfigStatus(context.workspaceRoot);
+    // implements REQ-agent-guided-migration-orchestration
+    // A schema upgrade plans the source rewrites kibi migrate performs with
+    // it; the planner loads only when an upgrade is due.
+    const sourcePlanner = schemaStatus.needsMigration
+      ? (await import("../../operations/migration/schema6.js"))
+          .buildSchema6MigrationFragment
+      : undefined;
     const migrationPlan = buildActionsFromStatus({
       workspaceRoot: context.workspaceRoot,
       branchAttachment: attachment,
@@ -1125,6 +1142,15 @@ export async function executeStatus(
         ? snapshotEvidence.snapshot.hash
         : null,
       configStatus: schemaStatus,
+      ...(sourcePlanner !== undefined
+        ? {
+            planSchemaUpgradeSources: (currentSchemaVersion: number | null) =>
+              sourcePlanner({
+                workspaceRoot: context.workspaceRoot,
+                currentSchemaVersion,
+              }),
+          }
+        : {}),
     });
     const listed = context.fs?.glob
       ? await context.fs.glob(

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 : "";
@@ -553,6 +616,14 @@ export function buildActionsFromCoverage(input: {
   return actions;
 }
 
+/** Source-rewrite actions a schema upgrade performs, as its planner returns them. */
+export type SchemaUpgradeSourceActions = Readonly<{
+  actions: readonly MigrationAction[];
+  /** Automatic actions that rewrite authored sources; the upgrade waits on them. */
+  sourceRewriteActionIds: readonly string[];
+  diagnostics: readonly string[];
+}>;
+
 export type MigrationConfigStatus = Readonly<{
   status: "missing" | "invalid" | "older" | "current" | "newer";
   currentVersion: number | null;
@@ -621,6 +692,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>>;
@@ -631,8 +714,17 @@ export function buildActionsFromStatus(input: {
   kbSnapshotId?: string | null;
   workspaceSnapshot?: string | null;
   configStatus?: MigrationConfigStatus;
+  /**
+   * Plans the authored-source rewrites `kibi migrate --yes` performs on its
+   * way to the latest schema (the planner `kibi migrate` itself uses), so
+   * the schema upgrade declares every file it touches. Read-only.
+   */
+  planSchemaUpgradeSources?: (
+    currentSchemaVersion: number | null,
+  ) => SchemaUpgradeSourceActions;
 }): MigrationPlan {
   const actions: MigrationAction[] = [];
+  const diagnostics: string[] = [];
   const attachment = input.branchAttachment;
   const store = input.branchStore;
   const configStatus =
@@ -686,17 +778,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({
@@ -735,6 +830,21 @@ export function buildActionsFromStatus(input: {
   if (configStatus.needsMigration || legacyStorageMigrationRequired) {
     const operatorOnly =
       configStatus.status === "newer" || legacyStorageBlocked;
+    // implements REQ-agent-guided-migration-orchestration, REQ-cli-schema-migration
+    // The source rewrites the migrate run performs (legacy-link marks, origin
+    // backfill, lifecycle repairs, ...) are planned as their own actions with
+    // their own files, and the upgrade waits on them, so approving it means
+    // approving them. Knowledge still outside .kb/ is planned after it moves.
+    const sources =
+      !operatorOnly &&
+      !legacyStorageMigrationRequired &&
+      input.planSchemaUpgradeSources !== undefined
+        ? input.planSchemaUpgradeSources(configStatus.currentVersion)
+        : null;
+    if (sources !== null) {
+      actions.push(...sources.actions);
+      diagnostics.push(...sources.diagnostics);
+    }
     actions.push(
       migrationAction({
         id: "schema-config-upgrade",
@@ -750,28 +860,44 @@ 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(" ")} 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.`,
+              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) ?? []),
+          // The migrate run keeps the canonical derived entries ignored.
+          ".gitignore",
+          // Unplanned source rewrites can touch any authored .kb/ file.
+          ...(sources === null ? [".kb/"] : []),
+          ...legacyStorage.moves.map((move) => move.from),
+          ...legacyStorage.removals.map((removal) => removal.path),
         ],
         evidence: {
           configStatus,
-          ...(legacyStorage === null
-            ? {}
-            : {
+          ...(sources === null
+            ? {
+                sourceRewrites:
+                  "Not planned as separate actions: kibi migrate --yes also marks coarse symbol links legacy-link, backfills origin and repairs lifecycle findings in authored .kb/ sources. The plan lists them as their own actions once the upgrade can run automatically on the canonical .kb/ layout.",
+              }
+            : {}),
+          ...(legacyStorageMigrationRequired
+            ? {
                 legacyStorage: {
                   moves: legacyStorage.moves,
+                  removals: legacyStorage.removals,
+                  conflicts: legacyStorage.conflicts,
                   blockers: legacyStorage.blockers,
                   legacyConfig: legacyStorage.legacyConfig,
                 },
-              }),
+              }
+            : {}),
         },
-        dependsOn: storeState === "missing" ? ["branch-store-ensure"] : [],
+        dependsOn: [
+          ...(storeState === "missing" ? ["branch-store-ensure"] : []),
+          ...(sources?.sourceRewriteActionIds ?? []),
+        ],
         autoApplicable: !operatorOnly,
       }),
     );
@@ -816,12 +942,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 +982,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({
@@ -940,5 +1066,6 @@ export function buildActionsFromStatus(input: {
     ],
     incompleteDomains,
     actions,
+    diagnostics,
   });
 }

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",
@@ -66,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, decision-firm-unreferenced, decision-firm-superseded, supersedes-reason-missing, supersedes-reason-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/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",