kibi-cli 2.22.1 → 2.24.0

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

@@ -22,6 +22,7 @@ import {
   WHY_THIS_CHANGED_HEADING,
   carriesFirmness,
   effectiveFirmness,
+  firmnessIsImplicit,
   firmnessRef,
   supersedeAcknowledgement,
   whyThisChangedWords,
@@ -66,6 +67,21 @@ const DECISION_LANES = ["requirements", "adr"] as const;
 /** The schema version from which a supersede must explain itself. */
 const SUPERSEDES_REASON_SCHEMA_VERSION = 9;
 
+/**
+ * The schema version from which a decision without `firmness` reads its
+ * firmness from its origin, so a person's or imported rule is firm.
+ */
+// implements REQ-kb-decision-firmness-from-origin
+export const FIRMNESS_FROM_ORIGIN_SCHEMA_VERSION = 10;
+
+/**
+ * Told on a KB older than schema 10: the pending schema upgrade acknowledges
+ * supersedes of decisions that only became firm when firmness started to
+ * follow origin.
+ */
+const PRE_SCHEMA10_FIRM_NOTE =
+  " This decision has no firmness and was not written by an agent, so it reads as firm from schema 10; supersedes recorded before schema 10 are acknowledged by the plan's schema-config-upgrade (kibi migrate --yes).";
+
 /**
  * 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.
@@ -167,6 +183,43 @@ export function supersedeAcknowledgements(
     .map((target) => supersedeAcknowledgement(id, target));
 }
 
+/**
+ * Supersede edges (`FROM -> TO`) whose target reads as firm only because
+ * firmness follows origin (it has no `firmness` and an agent did not write
+ * it) and whose superseder is not firm, retired entities included. These
+ * were allowed before schema 10; the migration acknowledges them once.
+ */
+// implements REQ-kb-decision-firmness-from-origin
+export function implicitFirmSupersedes(
+  entities: readonly AuthoredEntity[],
+  edges: ReadonlyMap<string, Set<string>>,
+): string[] {
+  const byId = new Map(entities.map((entity) => [entity.id, entity]));
+  const found: string[] = [];
+  for (const [from, targets] of edges) {
+    const source = byId.get(from);
+    if (
+      source === undefined ||
+      effectiveFirmness(
+        source.type,
+        source.data.firmness,
+        source.data.origin,
+      ) === "firm"
+    )
+      continue;
+    for (const to of targets) {
+      const target = byId.get(to);
+      if (
+        target !== undefined &&
+        firmnessIsImplicit(target.type, target.data.firmness) &&
+        effectiveFirmness(target.type, undefined, target.data.origin) === "firm"
+      )
+        found.push(supersedeAcknowledgement(from, to));
+    }
+  }
+  return found.sort();
+}
+
 /** Evaluate the firmness rules over authored requirements and ADRs. */
 // implements REQ-kb-decision-firmness
 export function evaluateDecisionFirmness(
@@ -174,11 +227,19 @@ 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 }> = {},
+  options: Readonly<{
+    schemaVersion?: number | null;
+    /** Edges the schema 10 migration recorded (`FROM -> TO`). */
+    firmSupersedeAcknowledged?: ReadonlySet<string>;
+  }> = {},
 ): Violation[] {
   const preSchema9 =
     typeof options.schemaVersion === "number" &&
     options.schemaVersion < SUPERSEDES_REASON_SCHEMA_VERSION;
+  const preSchema10 =
+    typeof options.schemaVersion === "number" &&
+    options.schemaVersion < FIRMNESS_FROM_ORIGIN_SCHEMA_VERSION;
+  const firmAcknowledged = options.firmSupersedeAcknowledged ?? new Set();
   const findings: Violation[] = [];
   const superseded = supersededIds(edges);
   const byId = new Map(entities.map((entity) => [entity.id, entity]));
@@ -186,11 +247,13 @@ export function evaluateDecisionFirmness(
     .filter((entity) => isCurrentAuthoredEntity(entity, superseded))
     .sort((left, right) => left.id.localeCompare(right.id));
   const firmnessOf = (entity: AuthoredEntity) =>
-    effectiveFirmness(entity.type, entity.data.firmness);
+    effectiveFirmness(entity.type, entity.data.firmness, entity.data.origin);
 
+  // Only an authored `firmness: firm` must cite the person's words: a
+  // decision that reads as firm from its origin already names its author.
   if (rules.has(DECISION_FIRM_UNREFERENCED_RULE)) {
     for (const entity of current) {
-      if (firmnessOf(entity) !== "firm") continue;
+      if (entity.data.firmness !== "firm") continue;
       if (firmnessRef({ type: entity.type, ...entity.data }) !== undefined)
         continue;
       findings.push({
@@ -212,13 +275,19 @@ export function evaluateDecisionFirmness(
       left.id.localeCompare(right.id),
     )) {
       if (firmnessOf(entity) === "firm") continue;
+      const implicit = new Set<string>();
       const firmTargets = [...(edges.get(entity.id) ?? [])]
         .filter((id) => {
           const target = byId.get(id);
-          return (
-            target !== undefined &&
-            effectiveFirmness(target.type, target.data.firmness) === "firm"
-          );
+          if (target === undefined || firmnessOf(target) !== "firm")
+            return false;
+          if (!firmnessIsImplicit(target.type, target.data.firmness))
+            return true;
+          // Recorded before firmness followed origin: acknowledged once.
+          if (firmAcknowledged.has(supersedeAcknowledgement(entity.id, id)))
+            return false;
+          implicit.add(id);
+          return true;
         })
         .sort();
       if (firmTargets.length === 0) continue;
@@ -226,8 +295,7 @@ export function evaluateDecisionFirmness(
         rule: DECISION_FIRM_SUPERSEDED_RULE,
         entityId: entity.id,
         description: `${entity.id} (firmness: ${firmnessOf(entity)}) supersedes the firm decision${firmTargets.length === 1 ? "" : "s"} ${firmTargets.join(", ")}; only a human may change a firm decision`,
-        suggestion:
-          "Ask the person who stated the firm decision; if they agree, mark the replacement firmness: firm with origin.ref to their words, otherwise remove the supersedes link and propose the change instead",
+        suggestion: `Ask the person who stated the firm decision; if they agree, mark the replacement firmness: firm with origin.ref to their words, otherwise remove the supersedes link and propose the change instead${preSchema10 && implicit.size > 0 ? `.${PRE_SCHEMA10_FIRM_NOTE}` : ""}`,
         source: entity.path,
         evidence: { firmness: firmnessOf(entity), firmTargets },
       });
@@ -291,6 +359,11 @@ export function collectDecisionFirmnessViolations(
     authoredSupersedes(workspaceRoot, entities),
     rules,
     new Set(manifest?.supersedesReasonAcknowledged ?? []),
-    { schemaVersion: manifest?.schemaVersion ?? null },
+    {
+      schemaVersion: manifest?.schemaVersion ?? null,
+      firmSupersedeAcknowledged: new Set(
+        manifest?.firmSupersedeAcknowledged ?? [],
+      ),
+    },
   );
 }

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";
@@ -8,6 +9,7 @@ import {
   type IntentSearchMatch,
   type SourceLocation,
   executeIntentSearch,
+  questionPaths,
   validateIntentSearchInput,
 } from "../../intent-search.js";
 import { classifyActivation } from "../../operations/bootstrap/activation.js";
@@ -34,6 +36,7 @@ import {
   reloadFullEntities,
   validateEntityType,
 } from "./discovery-entities.js";
+import { readAuthoredEntity } from "./entity-context.js";
 import {
   type MigrationConfigStatus,
   type MigrationPlan,
@@ -67,6 +70,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 +102,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 +707,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);
     }
@@ -704,11 +732,16 @@ export async function executeQuery(
     const indexedPage = prolog.queryEntities
       ? await prolog.queryEntities(pageInput, signal)
       : await queryEntitiesViaQuery(prolog, pageInput, signal);
-    // A requirement or ADR without authored firmness reads as `default`;
-    // the row says so, so a reader never has to know the default.
-    // implements REQ-kb-decision-firmness
+    // A requirement or ADR without authored firmness reads as its origin
+    // implies (`default` when an agent wrote it, else `firm`); the row says
+    // so, so a reader never has to know the rule.
+    // implements REQ-kb-decision-firmness, REQ-kb-decision-firmness-from-origin
     const paginated = indexedPage.entities.map((entity) => {
-      const firmness = effectiveFirmness(entity.type, entity.firmness);
+      const firmness = effectiveFirmness(
+        entity.type,
+        entity.firmness,
+        entity.origin,
+      );
       return firmness === undefined || entity.firmness === firmness
         ? entity
         : { ...entity, firmness };
@@ -729,12 +762,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 +787,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 +885,30 @@ 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.';
+
+// A file path written in the question is left out of its topic. Passed as
+// sourceLocations it also brings the requirements linked to that file.
+function questionPathHint(
+  query: string,
+  locations: readonly SourceLocation[] | undefined,
+): string {
+  const located = new Set(
+    (locations ?? []).map((location) => location.path.replace(/^\.\//, "")),
+  );
+  const named = questionPaths(query).filter((file) => !located.has(file));
+  if (named.length === 0) return "";
+  const list = named.join(", ");
+  return named.length === 1
+    ? ` The question names ${list}; its words were left out of the topic. Pass it as sourceLocations to also see the requirements linked to that file.`
+    : ` The question names ${list}; their words were left out of the topic. Pass them as sourceLocations to also see the requirements linked to those files.`;
+}
+
 export async function executeSearch(
   input: SearchInput,
   context: OperationContext,
@@ -864,14 +981,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}`;
+      }${questionPathHint(trimmedQuery, sourceLocations)}${CONTRADICTION_QUESTION.test(trimmedQuery) ? CONTRADICTION_HINT : ""}${storeNote}`;
       return {
         content: [{ type: "text", text }],
         structuredContent: {

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 clear it when the evidence is gone: kb_upsert with the entity's title, status and text_ref "".`;
+    }
+    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,

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

@@ -86,7 +86,7 @@ export const compileIntentSpec = {
         items: { type: "string", minLength: 1 },
         maxItems: 64,
         description:
-          "Optional complete atomic clause decomposition. Each assertive clause receives independent proposition accounting.",
+          "Optional complete atomic clause decomposition. Each clause must be a verbatim fragment of intent (whitespace may differ); a clause that does not occur in intent fails the call with VALIDATION_FAILED naming it. Each assertive clause receives independent proposition accounting.",
       },
       semanticFacets: {
         type: "object",

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

@@ -1,3 +1,4 @@
+import { confirmMetaFreshness } from "../../../utils/content-freshness.js";
 import { PROOF_RECEIPT_MAX_AGE_SECONDS } from "../../proof-receipt.js";
 import { executeStatus } from "../discovery-executors.js";
 import {
@@ -160,7 +161,7 @@ export async function executeFindGaps(
               : `Found ${payload.count ?? rows.length} gap rows. Showing ${rows.length}: ${rows.map((row) => row.id).join(", ")}.${stubNote}`,
         },
       ],
-      structuredContent: payload,
+      structuredContent: confirmMetaFreshness(payload, context.workspaceRoot),
     };
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
@@ -380,15 +381,16 @@ export async function executeCoverage(
     const migrationPlan = statusPlan
       ? mergeMigrationPlans([statusPlan, coveragePlan])
       : coveragePlan;
+    const confirmed = confirmMetaFreshness(payload, context.workspaceRoot);
     const enrichedPayload = {
-      ...payload,
+      ...confirmed,
       rows,
       ...(repairPlan !== undefined ? { repairPlan } : {}),
       ...(legacyMigrationPlan !== undefined ? { legacyMigrationPlan } : {}),
       ...(symbolRepairPlan !== undefined ? { symbolRepairPlan } : {}),
       migrationPlan,
       meta: {
-        ...(payload.meta ?? {}),
+        ...(confirmed.meta ?? {}),
         proofReceiptMaxAgeSeconds: PROOF_RECEIPT_MAX_AGE_SECONDS,
         proofSnapshot: codeSnapshot,
         proofSnapshotAvailable: snapshotEvidence.available,
@@ -512,7 +514,7 @@ export async function executeGraph(
               : `Graph traversal returned ${nodes.length} nodes and ${edges.length} edges from ${input.seedIds.join(", ")}.`,
         },
       ],
-      structuredContent: payload,
+      structuredContent: confirmMetaFreshness(payload, context.workspaceRoot),
     };
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);

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

@@ -144,7 +144,9 @@ export async function executeSemanticAdvisor(
     content: [
       {
         type: "text",
-        text: `kb_semantic_advisor: ${result.receipt.summary} Suggestions: ${result.receipt.suggestions.map(({ kind }) => kind).join(", ") || "none"}.`,
+        // A drift warning decides whether the analyzed ledger can be
+        // written at all, so the text says it too, not only the warnings.
+        text: `kb_semantic_advisor: ${result.receipt.summary} Suggestions: ${result.receipt.suggestions.map(({ kind }) => kind).join(", ") || "none"}.${ledgerWarnings.map((warning) => ` ${warning}`).join("")}`,
       },
     ],
     structuredContent: {
@@ -211,7 +213,7 @@ export const semanticAdvisorSpec = {
         type: "array",
         items: { type: "string" },
         description:
-          "Optional complete list of atomic requirement clauses supplied by the caller. Use this for compound prose so every normative clause receives a stable claim key and independent grounding review.",
+          "Optional complete list of atomic requirement clauses supplied by the caller. Each clause must be a verbatim fragment of text (whitespace may differ); a clause that does not occur in text fails the call with VALIDATION_FAILED naming it. Use this for compound prose so every normative clause receives a stable claim key and independent grounding review.",
       },
       interpretations: {
         type: "array",

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

@@ -14,7 +14,7 @@ export const upsertSpec = {
   name: "kb_upsert",
   cliName: "upsert",
   description:
-    "Create or update one entity and optional relationships. Use for KB mutations after validating intent; prefer a dryRun:true call first because it validates without writing and returns semantic advisor receipts for prose-heavy requirements. Use kb_model (mode requirement) before hand-writing strict property facts from prose, and kb_model (mode predicates) before hand-writing ontology predicate facts. Use the `relationships` array for batch creation of multiple links in a single call (e.g., linking a requirement to multiple tests or facts). Prefer modeling requirements as reusable fact links (`constrains`, `requires_property`, or `requires_predicate`) so consistency and contradiction checks remain queryable. Relationship endpoints must already exist in KB. For requirements, the write will be rejected if it contradicts existing current requirements that constrain the same subject with incompatible properties. To replace a conflicting requirement, include a `supersedes` relationship from the new requirement to the old one in the same request, then upsert the old requirement with status closed (kb_check blocks a superseded requirement that is not closed). Successful writes may return non-blocking semantic advisor warnings; inspect and repair those warnings before treating prose as contradiction-checkable. Pass a sectioned `document.body` when creating a requirement (the statement, then `## Context` stating why it exists, who asked and the source, then `## Source` with the verbatim excerpt) and a prose body for scenarios, tests, ADRs and observation facts; a result warning reports an entity whose body lacks context, and kb_check blocks it under entity-context-missing. Never invent a reason the requester did not give: write 'Reason not stated'. Do not use for read-only inspection. Side effects: writes KB, may refresh symbol coordinates; dryRun:true writes nothing.",
+    "Create or update one entity and optional relationships. Use for KB mutations after validating intent; prefer a dryRun:true call first because it validates without writing and returns semantic advisor receipts for prose-heavy requirements. Use kb_model (mode requirement) before hand-writing strict property facts from prose, and kb_model (mode predicates) before hand-writing ontology predicate facts. Use the `relationships` array for batch creation of multiple links in a single call (e.g., linking a requirement to multiple tests or facts). An update keeps the properties and relationships it leaves out: send the fields that change (with title and status) and only the links to add. Prefer modeling requirements as reusable fact links (`constrains`, `requires_property`, or `requires_predicate`) so consistency and contradiction checks remain queryable. Relationship endpoints must already exist in KB. For requirements, the write will be rejected if it contradicts existing current requirements that constrain the same subject with incompatible properties. To replace a conflicting requirement, include a `supersedes` relationship from the new requirement to the old one in the same request, then upsert the old requirement with status closed (kb_check blocks a superseded requirement that is not closed). Successful writes may return non-blocking semantic advisor warnings; inspect and repair those warnings before treating prose as contradiction-checkable. Pass a sectioned `document.body` when creating a requirement (the statement, then `## Context` stating why it exists, who asked and the source, then `## Source` with the verbatim excerpt) and a prose body for scenarios, tests, ADRs and observation facts; a result warning reports an entity whose body lacks context, and kb_check blocks it under entity-context-missing. Never invent a reason the requester did not give: write 'Reason not stated'. Do not use for read-only inspection. Side effects: writes KB, may refresh symbol coordinates; dryRun:true writes nothing.",
   businessInputSchema: {
     type: "object",
     required: ["type", "id", "properties"],

package/src/public/schemas/entity.ts

@@ -362,7 +362,7 @@ const entitySchema: Record<string, unknown> = {
       type: "string",
       enum: ["firm", "default", "exploratory"],
       description:
-        "Requirement and ADR only. How firmly the decision was made. firm: a human stated it as a rule; it needs a ref (origin.ref, or approval_ref on a requirement) to their words, and only a human may change it. default (assumed when absent): a delegated or agent choice; a later agent may supersede it with evidence. exploratory: a flagged guess, expected to be revisited.",
+        "Requirement and ADR only. How firmly the decision was made. firm: a human stated it as a rule; it needs a ref (origin.ref, or approval_ref on a requirement) to their words, and only a human may change it. default: a delegated or agent choice; a later agent may supersede it with evidence. exploratory: a flagged guess, expected to be revisited. When absent, it reads as default if an agent wrote the entity (origin.kind agent) and as firm otherwise (a person's, imported or migrated decision); set it explicitly when recording a decision.",
     },
     expects: {
       type: "string",