kibi-cli 2.22.0 → 2.23.0

package/src/public/impact/diagnostics.ts

@@ -81,6 +81,12 @@ function getGranularSymbolsForSourceFile(
   };
 }
 
+function hasTraceabilityLinks(symbol: ExtractedSymbol): boolean {
+  return (symbol.relationships ?? []).some((relationship) =>
+    isTraceabilityRelationshipType(relationship.type),
+  );
+}
+
 function formatRelationshipTargets(symbol: ExtractedSymbol): string {
   const targets = [
     ...new Set(
@@ -183,15 +189,26 @@ export function createSemanticReviewDiagnostics(
       if (!isChangedBehavioralReviewCandidate(symbol)) continue;
 
       const linkedTargets = formatRelationshipTargets(symbol);
+      const file = symbol.location.file;
+      // In a file no requirement owns at all, the changed behavior has no
+      // recorded intent, so the review is "record it", not "compare it with
+      // its links". Elsewhere a coarser symbol of the file may still own it.
+      const unlinked =
+        !hasTraceabilityLinks(symbol) &&
+        !(options.linkedSourceFiles?.has(file) ?? false);
       diagnostics.push({
         id: "symbol_semantic_review_needed",
         severity: "warning",
         blocking: false,
         category: "symbol",
-        files: [symbol.location.file],
+        files: [file],
         docs: ["docs/symbol-traceability-taxonomy.md"],
-        message: `Changed behavioral symbol ${symbol.name} needs semantic review against linked Kibi coverage: ${linkedTargets}`,
-        suggestion: `Use kb_search and kb_query for ${symbol.location.file}, then verify that ${linkedTargets} actually describe and test the changed behavior or UI copy. Update Kibi links or requirements/tests while the edit context is fresh.`,
+        message: unlinked
+          ? `Changed behavioral symbol ${symbol.name} is in a file no requirement owns, so no recorded intent covers the behavior it has after this change`
+          : `Changed behavioral symbol ${symbol.name} needs semantic review against linked Kibi coverage: ${linkedTargets}`,
+        suggestion: unlinked
+          ? `If the change adds or alters behavior, record it with the change: kb_search({query:"<the behavior>", sourceLocations:[{path:"${file}"}]}) for a requirement that already describes it and link ${symbol.name} to it; if none does, kb_upsert a requirement with a scenario and link the symbol with implements. If behavior is unchanged (a refactor, renaming), say so in the final report instead.`
+          : `Use kb_search and kb_query for ${file}, then verify that ${linkedTargets} actually describe and test the changed behavior or UI copy. Update Kibi links or requirements/tests while the edit context is fresh.`,
       });
     }
   }

package/src/public/impact/types.ts

@@ -49,6 +49,8 @@ export type SymbolGranularityDiagnosticsOptions = {
 
 export type SemanticReviewDiagnosticsOptions = {
   readonly symbolsByFile: SymbolsByFile;
+  /** Source files where some manifest symbol carries a traceability link. */
+  readonly linkedSourceFiles?: ReadonlySet<string>;
 };
 
 export type SymbolQualityDiagnosticsOptions = {

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

@@ -32,12 +32,14 @@ import {
   buildSummary,
 } from "./check-format-shared.js";
 import {
+  SCOPED_CHECK_OMITTED_ID,
   analyzeKbCheckImpact,
   collectQueryPlanSafetyViolations,
   getEffectiveRules,
   partitionCheckFindings,
   qualityDiagnosticsFromImpact,
   resolveCheckRules,
+  scopeQualityDiagnosticsToImpact,
   stagedEntityIdStyleDiagnostics,
 } from "./check-helpers.js";
 import { collectCheckPolicyViolations } from "./check-policy-rules.js";
@@ -430,8 +432,17 @@ export async function executeCheck(
             now: context.clock(),
             ...maxDiagnosticsOption,
           });
+    // A check scoped to sourceFiles answers about those files; the KB-wide
+    // advisory scan only lists what concerns them.
+    const advisoryQualityDiagnostics =
+      impactResult && args.sourceFiles !== undefined && !hasExplicitRules
+        ? scopeQualityDiagnosticsToImpact(
+            partitioned.qualityDiagnostics,
+            impactResult,
+          )
+        : partitioned.qualityDiagnostics;
     const qualityDiagnostics = [
-      ...partitioned.qualityDiagnostics,
+      ...advisoryQualityDiagnostics,
       ...extraQualityDiagnostics,
     ];
 
@@ -439,9 +450,10 @@ export async function executeCheck(
     const migrationPlan = await migrationPlanForCheck(
       context,
       violations,
-      qualityDiagnostics as unknown as readonly Readonly<
-        Record<string, unknown>
-      >[],
+      // The omitted-findings count is a pointer, not a repair to plan.
+      qualityDiagnostics.filter(
+        (diagnostic) => diagnostic.id !== SCOPED_CHECK_OMITTED_ID,
+      ) as unknown as readonly Readonly<Record<string, unknown>>[],
       statusPlan,
     );
     return {

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

@@ -80,6 +80,71 @@ export function partitionCheckFindings(findings: readonly Violation[]): {
   return { violations, qualityDiagnostics };
 }
 
+export const SCOPED_CHECK_OMITTED_ID = "scoped_check_omitted_quality";
+const OMITTED_RULES_SHOWN = 5;
+
+/**
+ * Advisory rule findings of a check scoped to `sourceFiles` that concern
+ * those files: findings on an entity a changed file's symbols link to (or on
+ * those symbols) and findings whose source is one of the files. The KB-wide rest (unapproved requirements elsewhere,
+ * unrelated scenarios) is reduced to one info diagnostic with per-rule counts,
+ * so a check after a small edit answers about that edit; kb_check without
+ * sourceFiles still lists every finding.
+ */
+// implements REQ-cli-check
+export function scopeQualityDiagnosticsToImpact(
+  diagnostics: readonly QualityDiagnostic[],
+  impactResult: ChangedFileImpactResult,
+): QualityDiagnostic[] {
+  const normalizePath = (value: string) =>
+    value.replace(/\\/g, "/").replace(/^\.\//, "");
+  const files = new Set(impactResult.sourceFiles.map(normalizePath));
+  const entityIds = new Set<string>();
+  for (const linked of impactResult.linkedEntities) {
+    entityIds.add(linked.id);
+    entityIds.add(linked.sourceSymbolId);
+  }
+  const inScope = (diagnostic: QualityDiagnostic) =>
+    (diagnostic.entityId !== undefined && entityIds.has(diagnostic.entityId)) ||
+    (diagnostic.source !== undefined &&
+      files.has(normalizePath(diagnostic.source))) ||
+    (diagnostic.files ?? []).some((file) => files.has(normalizePath(file)));
+
+  const kept: QualityDiagnostic[] = [];
+  const omittedByRule = new Map<string, number>();
+  for (const diagnostic of diagnostics) {
+    if (inScope(diagnostic)) {
+      kept.push(diagnostic);
+      continue;
+    }
+    const rule = diagnostic.id.replace(/^rule\./, "");
+    omittedByRule.set(rule, (omittedByRule.get(rule) ?? 0) + 1);
+  }
+  if (omittedByRule.size === 0) return kept;
+
+  const omitted = [...omittedByRule.values()].reduce((a, b) => a + b, 0);
+  const rules = [...omittedByRule.entries()].sort(
+    (a, b) => b[1] - a[1] || a[0].localeCompare(b[0]),
+  );
+  const shown = rules
+    .slice(0, OMITTED_RULES_SHOWN)
+    .map(([rule, count]) => `${rule} ×${count}`);
+  if (rules.length > OMITTED_RULES_SHOWN) {
+    shown.push(`${rules.length - OMITTED_RULES_SHOWN} more rules`);
+  }
+  kept.push({
+    id: SCOPED_CHECK_OMITTED_ID,
+    severity: "info",
+    blocking: false,
+    category: "integrity",
+    message: `This check is scoped to ${files.size} source ${files.size === 1 ? "file" : "files"}; ${omitted} advisory ${omitted === 1 ? "finding" : "findings"} elsewhere in the KB ${omitted === 1 ? "is" : "are"} not listed (${shown.join(", ")}). None of them concerns the checked files.`,
+    suggestion:
+      "Run kb_check without sourceFiles for the full KB audit when it matters to the task.",
+    evidence: { omitted, byRule: Object.fromEntries(rules) },
+  });
+  return kept;
+}
+
 function resolveChecksPlPath(): string {
   const override = getKbPlPathOverride();
   return path.join(path.dirname(override ?? resolveKbPlPath()), "checks.pl");

package/src/public/operations/contracts.ts

@@ -447,6 +447,7 @@ const BASE_DATA_SCHEMAS: Readonly<
       count: integerValue,
       factQuery: recordValue,
       branchStore: recordValue,
+      body: recordValue,
     },
     ["entities", "count"],
   ),

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

@@ -1,3 +1,4 @@
+import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { compilerFingerprintReason } from "../../commands/sync/cache.js";
 import { effectiveFirmness } from "../../decision-firmness.js";
@@ -34,6 +35,7 @@ import {
   reloadFullEntities,
   validateEntityType,
 } from "./discovery-entities.js";
+import { readAuthoredEntity } from "./entity-context.js";
 import {
   type MigrationConfigStatus,
   type MigrationPlan,
@@ -67,6 +69,8 @@ export type QueryInput = {
   readonly distinct?: string;
   readonly subjectKey?: string;
   readonly propertyKey?: string;
+  /** With `id`: also return the entity's authored Markdown body. */
+  readonly includeBody?: boolean;
 };
 
 /** A ready-to-run follow-up call the query suggests. */
@@ -97,8 +101,26 @@ export type QueryPayload = {
   readonly factQuery?: FactQueryPayload;
   /** Present when an empty answer came from a store never compiled for this branch. */
   readonly branchStore?: SearchBranchStoreNotice;
+  /** Present when `includeBody` was requested for an `id`. */
+  readonly body?: QueryBody;
 };
 
+/**
+ * The authored Markdown body of the entity a kb_query `id` names: the text
+ * after its front matter, which kb_upsert `document.body` replaces. `text` is
+ * null when the entity has no readable authored document (a symbol, or a
+ * source that is not a workspace Markdown file).
+ */
+export type QueryBody = Readonly<{
+  id: string;
+  path: string | null;
+  text: string | null;
+  truncated?: boolean;
+}>;
+
+/** Bodies longer than this are cut; the file itself stays the full record. */
+export const QUERY_BODY_MAX_CHARS = 32_000;
+
 export const FACT_KINDS = [
   "subject",
   "property_value",
@@ -684,6 +706,11 @@ export async function executeQuery(
   const { type, id, tags, sourceFile, limit = 100, offset = 0 } = input;
   try {
     validateEntityType(type);
+    if (input.includeBody === true && (id === undefined || id === "")) {
+      throw new Error(
+        "includeBody needs id: it returns the authored body of one entity. Pass the entity's id.",
+      );
+    }
     if (hasTypedFactFilters(input)) {
       return await executeFactQuery(input, context, limit, offset);
     }
@@ -729,12 +756,23 @@ export async function executeQuery(
               return `${entityId} (${String(entity.title ?? "")}, status=${String(entity.status ?? "")})`;
             })
             .join(", ")}`;
+    const body =
+      input.includeBody === true && id !== undefined
+        ? await readQueryBody(
+            id,
+            paginated.find((entity) => entity.id === id),
+            context,
+          )
+        : undefined;
     return {
-      content: [{ type: "text", text }],
+      content: [
+        { type: "text", text: body ? `${text}\n${queryBodyText(body)}` : text },
+      ],
       structuredContent: {
         entities: paginated,
         count: indexedPage.count,
         ...(storeNotice ? { branchStore: storeNotice } : {}),
+        ...(body ? { body } : {}),
       },
     };
   } catch (error) {
@@ -743,6 +781,55 @@ export async function executeQuery(
   }
 }
 
+// The body is read from the entity's authored document inside the
+// workspace, the same file kb_upsert rewrites; nothing outside it is read.
+// implements REQ-kibi-operation-interface-parity
+async function readQueryBody(
+  id: string,
+  entity: Readonly<Record<string, unknown>> | undefined,
+  context: OperationContext,
+): Promise<QueryBody> {
+  const source = typeof entity?.source === "string" ? entity.source : "";
+  const relative = source.split("#", 1)[0]?.trim() ?? "";
+  const root = path.resolve(context.workspaceRoot);
+  const resolved = path.resolve(root, relative);
+  if (!relative.endsWith(".md") || !resolved.startsWith(root + path.sep)) {
+    return { id, path: null, text: null };
+  }
+  const bodyPath = path.relative(root, resolved).split(path.sep).join("/");
+  let raw: string;
+  try {
+    raw = String(
+      context.fs
+        ? await context.fs.readFile(resolved)
+        : await readFile(resolved, "utf8"),
+    );
+  } catch {
+    return { id, path: bodyPath, text: null };
+  }
+  const authored = readAuthoredEntity(raw, bodyPath)?.body;
+  if (authored === undefined || authored === null) {
+    return { id, path: bodyPath, text: null };
+  }
+  return authored.length > QUERY_BODY_MAX_CHARS
+    ? {
+        id,
+        path: bodyPath,
+        text: authored.slice(0, QUERY_BODY_MAX_CHARS),
+        truncated: true,
+      }
+    : { id, path: bodyPath, text: authored };
+}
+
+function queryBodyText(body: QueryBody): string {
+  if (body.text === null) {
+    return body.path === null
+      ? `No authored document for ${body.id}, so there is no body to return.`
+      : `The authored document ${body.path} of ${body.id} could not be read.`;
+  }
+  return `Body of ${body.id} (${body.path}${body.truncated ? `, first ${QUERY_BODY_MAX_CHARS} characters` : ""}; replace it with kb_upsert document.body):\n${body.text}`;
+}
+
 /**
  * Identifying metadata a caller needs to decide which hits to open.
  *
@@ -792,6 +879,13 @@ async function projectMatches<
     : matches.map(summarizeMatch);
 }
 
+// A question about contradictions is answered by the check, not by the
+// entities that happen to mention the word.
+const CONTRADICTION_QUESTION =
+  /\b(contradict\w*|conflict\w*|inconsisten\w*)\b/i;
+const CONTRADICTION_HINT =
+  ' Search only finds entities that mention a conflict. Whether current requirements contradict each other is decided by kb_check with rules ["domain-contradictions"]; what a proposed rule would conflict with, by kb_model mode predicates (decisionConflicts) on its text or a kb_upsert dryRun.';
+
 export async function executeSearch(
   input: SearchInput,
   context: OperationContext,
@@ -864,14 +958,14 @@ export async function executeSearch(
       );
       const text = `${
         intentResult.matches.length === 0
-          ? `No intent search results for '${trimmedQuery}' (abstained).`
+          ? `No intent search results for '${trimmedQuery}' (abstained). No entity shares enough of the question's words: ask again in the words and language the KB is written in, or pass sourceLocations.`
           : `Found ${intentResult.matches.length} intent search results for '${trimmedQuery}'${intentResult.analysis.ambiguous ? " (top matches are close; confirm before relying on one)" : ""}. Top: ${paginated
               .slice(0, 5)
               .map((match) => String(match.entity.id ?? ""))
               .join(
                 ", ",
               )}${answerLayer ? `. Governing: ${answerLayer.governing.map((req) => req.id).join(", ") || "none found"}` : ""}${topUngoverned ? ` (the top match ${topUngoverned.id} is linked to no requirement)` : ""}.`
-      }${storeNote}`;
+      }${CONTRADICTION_QUESTION.test(trimmedQuery) ? CONTRADICTION_HINT : ""}${storeNote}`;
       return {
         content: [{ type: "text", text }],
         structuredContent: {
@@ -1121,6 +1215,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,
@@ -1135,6 +1236,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

@@ -616,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;
@@ -706,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 =
@@ -813,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",
@@ -835,11 +867,21 @@ export function buildActionsFromStatus(input: {
           ".kb/manifest.json",
           ".kb/migrations",
           ".kb/config.json",
+          // 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,
+          ...(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: {
@@ -852,7 +894,10 @@ export function buildActionsFromStatus(input: {
               }
             : {}),
         },
-        dependsOn: storeState === "missing" ? ["branch-store-ensure"] : [],
+        dependsOn: [
+          ...(storeState === "missing" ? ["branch-store-ensure"] : []),
+          ...(sources?.sourceRewriteActionIds ?? []),
+        ],
         autoApplicable: !operatorOnly,
       }),
     );
@@ -1021,5 +1066,6 @@ export function buildActionsFromStatus(input: {
     ],
     incompleteDomains,
     actions,
+    diagnostics,
   });
 }

package/src/public/operations/schema6-check-actions.ts

@@ -208,6 +208,8 @@ export function supersessionCycleReviewActionInput(cycle: {
 export type SourcePathRewriteInput = Readonly<{
   entityId: string;
   file: string;
+  /** The field rewritten; absent means `source`. */
+  field?: "text_ref";
   from: string;
   to: string;
 }>;
@@ -260,7 +262,7 @@ export function sourcePathRewriteActionInput(
     ],
     evidence: {
       reason:
-        "The authored source field is dead data: the compiled source is always the entity's own file, and Kibi ignores the field when compiling and never writes it. Each rewrite points a knowledge file named by its pre-canonical path (under documentation/, or relative to the knowledge root) at the same file under .kb/. Each removal deletes a value that names the entity's own file (reason self) or nothing Kibi can map (reason dangling). Only the source line changes.",
+        "The authored source field is dead data: the compiled source is always the entity's own file, and Kibi ignores the field when compiling and never writes it. Each rewrite points a knowledge file named by its pre-canonical path (under documentation/, or relative to the knowledge root) at the same file under .kb/; a rewrite with field text_ref does the same for a text_ref evidence path. Each removal deletes a source value that names the entity's own file (reason self) or nothing Kibi can map (reason dangling). Only the rewritten or removed line changes.",
       count: all.length,
       rewrites: rewrites.map((rewrite) => ({ ...rewrite })),
       removals: removals.map((removal) => ({ ...removal })),
@@ -275,6 +277,8 @@ export function sourcePathRewriteActionInput(
 // implements REQ-kibi-schema6-migration, REQ-core-validation-rules, REQ-kibi-kb-lifecycle-integrity
 export function sourcePathReviewActionInput(source: {
   entityId: string;
+  /** The field to repair; absent means `source`. */
+  field?: "text_ref";
   value: unknown;
   file?: string;
   reason?: string;
@@ -285,6 +289,32 @@ export function sourcePathReviewActionInput(source: {
       ? source.value
       : JSON.stringify(source.value);
   const where = source.file !== undefined ? ` in ${source.file}` : "";
+  if (source.field === "text_ref") {
+    const edit =
+      source.rewrite !== undefined
+        ? `replace the whole field with the single line 'text_ref: ${source.rewrite}'`
+        : "point text_ref at the evidence file's current path, or delete the field when that evidence is gone";
+    return {
+      id: `review-text-ref-dangling-${stableIdPart(source.entityId)}`,
+      code: SOURCE_PATH_REVIEW_CODE,
+      category: "quality",
+      safety: "review",
+      invocation: {
+        kind: "review",
+        instruction: `${source.entityId} has text_ref '${shown}'${where}, a file path that does not exist (${source.reason ?? "the edit would not read back as exactly that change"}). A person edits the frontmatter by hand: ${edit}. Then rerun kibi migrate.`,
+      },
+      affectedEntityIds: [source.entityId],
+      affectedFiles: source.file !== undefined ? [source.file] : [],
+      dispositionRequired: true,
+      evidence: {
+        entityId: source.entityId,
+        field: "text_ref",
+        text_ref: source.value,
+        ...(source.reason !== undefined ? { refused: source.reason } : {}),
+        ...(source.rewrite !== undefined ? { rewrite: source.rewrite } : {}),
+      },
+    };
+  }
   const edit =
     source.rewrite !== undefined
       ? `replace the whole field with the single line 'source: ${source.rewrite}'`
@@ -367,10 +397,12 @@ export function lifecycleActionsFromViolations(
         typeof evidence.value === "string"
           ? evidence.value
           : (JSON.stringify(evidence.value) ?? "");
+      const textRef = evidence.field === "text_ref";
       if (refused !== "" || file === "") {
         actions.push(
           sourcePathReviewActionInput({
             entityId,
+            ...(textRef ? { field: "text_ref" as const } : {}),
             value: evidence.value,
             ...(file !== "" ? { file } : {}),
             ...(refused !== "" ? { reason: refused } : {}),
@@ -378,7 +410,16 @@ export function lifecycleActionsFromViolations(
           }),
         );
       } else if (rewrite !== "") {
-        rewrites.push({ entityId, file, from, to: rewrite });
+        rewrites.push({
+          entityId,
+          file,
+          ...(textRef ? { field: "text_ref" as const } : {}),
+          from,
+          to: rewrite,
+        });
+      } else if (textRef) {
+        // Kibi never removes evidence; an unmapped text_ref carries refused.
+        continue;
       } else {
         removals.push({
           entityId,

package/src/public/operations/source-path-dangling.ts

@@ -23,11 +23,17 @@ import {
 } from "../../operations/migration/source-paths.js";
 import type { Violation } from "../../utils/rule-registry.js";
 
-/** An authored source field that names no path, entity or URL. */
+/** An authored source field that names no path, entity or URL, or a path-shaped text_ref that names no file. */
 // implements REQ-core-validation-rules, REQ-kibi-kb-lifecycle-integrity
 export const SOURCE_PATH_DANGLING_RULE = "source-path-dangling";
 
 function suggestion(source: SourceRepair): string {
+  if (source.field === "text_ref") {
+    if (source.refused !== undefined) {
+      return `kibi migrate cannot repair this text_ref (${source.refused}), so it plans a review_source_path_dangling action. Point text_ref at the evidence file's current path, or remove it when the evidence is gone.`;
+    }
+    return `The file moved to ${source.fix.kind === "rewrite" ? source.fix.to : source.file}; kibi migrate rewrites the text_ref field there (source_path_rewrite).`;
+  }
   const compiled = `The compiled source is always the entity's own file (${source.file}), so the field carries nothing Kibi compiles.`;
   if (source.refused !== undefined) {
     return `kibi migrate cannot edit this source field safely (${source.refused}), so it plans a review_source_path_dangling action for a person. ${compiled}`;
@@ -54,10 +60,14 @@ export function sourcePathDanglingViolations(
   return dangling.map((source) => ({
     rule: SOURCE_PATH_DANGLING_RULE,
     entityId: source.entityId,
-    description: `${source.entityId} names source '${shownSourceValue(source.value)}', which is not an existing workspace path, an entity id or an http(s) URL`,
+    description:
+      source.field === "text_ref"
+        ? `${source.entityId} names text_ref '${shownSourceValue(source.value)}', a file path that does not exist in the workspace`
+        : `${source.entityId} names source '${shownSourceValue(source.value)}', which is not an existing workspace path, an entity id or an http(s) URL`,
     suggestion: suggestion(source),
     source: source.file,
     evidence: {
+      ...(source.field === "text_ref" ? { field: "text_ref" } : {}),
       value: source.value,
       file: source.file,
       ...(source.fix.kind === "rewrite"

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

@@ -132,6 +132,12 @@ export const querySpec = {
         description:
           "Optional zero-based pagination offset. Default: 0. Example: 50 to skip first 50 rows.",
       },
+      includeBody: {
+        type: "boolean",
+        default: false,
+        description:
+          "With id only: also return the entity's authored Markdown body (the prose after its front matter) as body {id, path, text}, so a stale statement in it can be corrected; kb_upsert document.body replaces it. Default: false.",
+      },
     },
   },
   requiresProlog: true,