kibi-cli 2.21.2 → 2.22.0

package/dist/traceability/staged-symbols-manifest.js

@@ -264,8 +264,7 @@ function getEffectiveManifestRecords(options) {
         stagedCoordinateArtifact,
     };
 }
-/** Max missing/extra symbol titles surfaced per file before "+N more". */
-const MAX_DETAIL_ITEMS = 6;
+// implements REQ-cli-staged-impact-enforcement
 function diffSymbolEvidence(sourcePath, expectedSymbols, stagedSymbols) {
     const stagedTitles = new Set(stagedSymbols.map((symbol) => symbol.title));
     const expectedTitles = new Set(expectedSymbols.map((symbol) => symbol.title));
@@ -282,12 +281,14 @@ function diffSymbolEvidence(sourcePath, expectedSymbols, stagedSymbols) {
     if (missing.length === 0 && extra.length === 0) {
         return null;
     }
+    // Keep the complete lists: human-facing renderers truncate (with an
+    // accurate "… and N more"), while JSON evidence carries every name.
     return {
         path: sourcePath,
         expectedCount: expectedSymbols.length,
-        coveredCount: stagedSymbols.length,
-        missing: missing.slice(0, MAX_DETAIL_ITEMS),
-        extra: extra.slice(0, MAX_DETAIL_ITEMS),
+        coveredCount: expectedSymbols.length - missing.length,
+        missing,
+        extra,
     };
 }
 export function assessStagedSymbolsManifest(options) {

package/dist/traceability/validate.d.ts

@@ -1,4 +1,5 @@
-import type { PrologProcess } from "../prolog.js";
+import { type PrologProcess } from "../prolog.js";
+import { type ParsedViolation } from "../prolog/codec.js";
 export interface ValidationOptions {
     minLinks: number;
     prolog: PrologProcess;
@@ -17,6 +18,18 @@ declare function splitTopLevelComma(s: string): string[];
 declare function splitTopLevelLists(value: string): string[];
 declare function parsePrologListOfLists(value: string): string[][];
 export declare function validateStagedSymbols(options: ValidationOptions): Promise<Violation[]>;
+/**
+ * Full-check `symbol-coverage` for the staged change set: the changed source
+ * symbols in the consulted overlay plus `extraSymbolIds` (symbols whose staged
+ * manifest entry changed). The Prolog rule is the one `kibi check` runs, so a
+ * commit cannot pass the staged gate with coverage the full check rejects.
+ */
+export declare function validateStagedSymbolCoverage(options: {
+    prolog: PrologProcess;
+    extraSymbolIds?: readonly string[];
+}): Promise<ParsedViolation[]>;
+/** Text lines for staged symbol-coverage violations, in `kibi check` form. */
+export declare function formatCoverageViolations(violations: readonly ParsedViolation[]): string;
 export declare function formatViolations(violations: Violation[]): string;
 export declare const __test__: {
     unquoteAtom: typeof unquoteAtom;

package/dist/traceability/validate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/traceability/validate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,aAAa,CAAC;CACvB;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,iBAAS,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAO1C;AAED,iBAAS,kBAAkB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CA0B/C;AAED,iBAAS,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CA8CnD;AAED,iBAAS,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,CAuBzD;AAGD,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,SAAS,EAAE,CAAC,CAgDtB;AAED,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,SAAS,EAAE,GAAG,MAAM,CAkBhE;AAGD,eAAO,MAAM,QAAQ;;;;;CAKpB,CAAC"}
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/traceability/validate.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,aAAa,EAAmB,MAAM,cAAc,CAAC;AACnE,OAAO,EACL,KAAK,eAAe,EAIrB,MAAM,oBAAoB,CAAC;AAE5B,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,aAAa,CAAC;CACvB;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,iBAAS,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAO1C;AAED,iBAAS,kBAAkB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CA0B/C;AAED,iBAAS,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CA8CnD;AAED,iBAAS,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,CAuBzD;AAGD,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,SAAS,EAAE,CAAC,CAgDtB;AAED;;;;;GAKG;AAEH,wBAAsB,4BAA4B,CAAC,OAAO,EAAE;IAC1D,MAAM,EAAE,aAAa,CAAC;IACtB,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAgB7B;AAED,8EAA8E;AAE9E,wBAAgB,wBAAwB,CACtC,UAAU,EAAE,SAAS,eAAe,EAAE,GACrC,MAAM,CAaR;AAED,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,SAAS,EAAE,GAAG,MAAM,CAkBhE;AAGD,eAAO,MAAM,QAAQ;;;;;CAKpB,CAAC"}

package/dist/traceability/validate.js

@@ -1,3 +1,6 @@
+import path from "node:path";
+import { resolveKbPlPath } from "../prolog.js";
+import { escapeAtom, parseViolationRows, toPrologAtom, } from "../prolog/codec.js";
 function unquoteAtom(value) {
     // remove surrounding single quotes and unescape doubled quotes
     const trimmed = value.trim();
@@ -141,6 +144,44 @@ export async function validateStagedSymbols(options) {
     }
     return violations;
 }
+/**
+ * Full-check `symbol-coverage` for the staged change set: the changed source
+ * symbols in the consulted overlay plus `extraSymbolIds` (symbols whose staged
+ * manifest entry changed). The Prolog rule is the one `kibi check` runs, so a
+ * commit cannot pass the staged gate with coverage the full check rejects.
+ */
+// implements REQ-014
+export async function validateStagedSymbolCoverage(options) {
+    const extra = `[${[...new Set(options.extraSymbolIds ?? [])]
+        .sort()
+        .map(toPrologAtom)
+        .join(",")}]`;
+    const checksPl = escapeAtom(path.join(path.dirname(resolveKbPlPath()), "checks.pl"));
+    const goal = `(use_module('${checksPl}'), call(checks:check_changed_symbol_coverage(${extra}, Violations)))`;
+    const res = await options.prolog.query(goal);
+    if (!res.success) {
+        throw new Error(`Prolog symbol-coverage query failed: ${res.error || "unknown error"}`);
+    }
+    return parseViolationRows(res.bindings.Violations ?? "[]");
+}
+/** Text lines for staged symbol-coverage violations, in `kibi check` form. */
+// implements REQ-014
+export function formatCoverageViolations(violations) {
+    if (violations.length === 0)
+        return "";
+    const lines = [
+        `Found ${violations.length} symbol-coverage violation(s) in staged symbols (the same rule kibi check runs):`,
+    ];
+    for (const violation of violations) {
+        lines.push("", `[${violation.rule}] ${violation.entityId}`);
+        if (violation.source)
+            lines.push(`  Source: ${violation.source}`);
+        lines.push(`  ${violation.description}`);
+        if (violation.suggestion)
+            lines.push(`  Suggestion: ${violation.suggestion}`);
+    }
+    return lines.join("\n");
+}
 export function formatViolations(violations) {
     // implements REQ-014
     if (!violations || violations.length === 0)

package/dist/utils/rule-registry.generated.d.ts

@@ -13,6 +13,11 @@ export declare const GENERATED_RULES: readonly [{
     readonly description: "Production symbols must directly implement requirements for ownership; covered_by is coverage only and executable_for is test identity only";
     readonly enforcementClass: "canonical";
     readonly category: "traceability";
+}, {
+    readonly name: "symbol-granularity";
+    readonly description: "A symbol with traceability relationships must not link its source file coarsely while narrower behavioral symbols are available, unless it carries an allowed granularity_reason; the staged gate's symbol_granularity_violation evaluated KB-wide";
+    readonly enforcementClass: "canonical";
+    readonly category: "traceability";
 }, {
     readonly name: "no-dangling-refs";
     readonly description: "All relationship targets must exist in the KB";

package/dist/utils/rule-registry.generated.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rule-registry.generated.d.ts","sourceRoot":"","sources":["../../src/utils/rule-registry.generated.ts"],"names":[],"mappings":"AAUA,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAyWlB,CAAC"}
+{"version":3,"file":"rule-registry.generated.d.ts","sourceRoot":"","sources":["../../src/utils/rule-registry.generated.ts"],"names":[],"mappings":"AAUA,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgXlB,CAAC"}

package/dist/utils/rule-registry.generated.js

@@ -26,6 +26,12 @@ export const GENERATED_RULES = [
         enforcementClass: "canonical",
         category: "traceability",
     },
+    {
+        name: "symbol-granularity",
+        description: "A symbol with traceability relationships must not link its source file coarsely while narrower behavioral symbols are available, unless it carries an allowed granularity_reason; the staged gate's symbol_granularity_violation evaluated KB-wide",
+        enforcementClass: "canonical",
+        category: "traceability",
+    },
     {
         name: "no-dangling-refs",
         description: "All relationship targets must exist in the KB",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-cli",
-  "version": "2.21.2",
+  "version": "2.22.0",
   "type": "module",
   "description": "Kibi CLI for knowledge base management",
   "engines": {
@@ -235,8 +235,8 @@
     "fast-glob": "^3.2.12",
     "gray-matter": "^4.0.3",
     "js-yaml": "^4.1.0",
-    "kibi-core": "^0.21.1",
-    "kibi-plugin-builtin": "^0.5.1",
+    "kibi-core": "^0.22.0",
+    "kibi-plugin-builtin": "^0.5.2",
     "kibi-plugin-sdk": "^0.5.0",
     "kibi-swipl": "^1.0.1",
     "saxes": "^6.0.0",

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/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);

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(" ")} 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) ?? []),
+          ...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",
@@ -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",