kibi-cli 2.1.0 → 2.2.0

package/src/public/operations/predicate-schema-conformance.ts

@@ -0,0 +1,362 @@
+/*
+ Kibi — repo-local, per-branch, queryable long-term memory for software projects
+ Copyright (C) 2026 Piotr Franczyk
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Affero General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License
+ along with this program.  If not, see <https://www.gnu.org/licenses/>.
+*/
+
+import { BUILT_IN_PREDICATE_SCHEMAS } from "../../operations/modeling/predicate-catalog.js";
+import {
+  type ArgumentRewrite,
+  type UndeclaredArgument,
+  applyArgumentRewrites,
+  predicateArgumentConformance,
+  predicateCanonicalKey,
+  predicateVocabularyErrors,
+  predicateVocabularyFromEntity,
+} from "../../operations/modeling/predicate-vocabulary.js";
+import type { Violation } from "../../utils/rule-registry.js";
+import entitySchema from "../schemas/entity.js";
+import { loadEntitiesPaged } from "./discovery-entities.js";
+import type { PrologPort } from "./runtime-types.js";
+
+const RULE = "predicate-schema-conformance";
+
+/** Every property the public entity schema accepts. */
+const AUTHORED_FIELDS: ReadonlySet<string> = new Set(
+  Object.keys(entitySchema.properties as Record<string, unknown>),
+);
+const DEFAULT_NAMESPACE = "default";
+
+/** Fields that belong to the compiled entity, not to an authored upsert. */
+const NON_AUTHORED_FIELDS = new Set([
+  "id",
+  "type",
+  "source",
+  "sourceFile",
+  "created_at",
+  "updated_at",
+  "links",
+  "relationships",
+]);
+
+type Entity = Readonly<Record<string, unknown>>;
+
+type SchemaRef = Readonly<{
+  schemaId: string;
+  namespace: string;
+  origin: "project_local" | "built_in";
+  argumentNames: readonly string[];
+  entity?: Entity;
+}>;
+
+/**
+ * Exact kb_upsert input that repairs one predicate fact mechanically: move it
+ * to the only namespace whose schema matches, and/or replace alias spellings
+ * with their declared constants. Present only when nothing is left for review.
+ */
+// implements REQ-kibi-predicate-vocabulary-migration
+export type PredicateFactRepair = Readonly<{
+  type: "fact";
+  id: string;
+  properties: Readonly<Record<string, unknown>>;
+}>;
+
+// implements REQ-kibi-predicate-vocabulary-migration
+export type PredicateConformanceEvidence = Readonly<{
+  factId: string;
+  predicateName: string;
+  namespace: string;
+  arity: number;
+  issue: "missing_schema" | "undeclared_constant" | "alias_in_use";
+  schemaId: string | null;
+  alignment: Readonly<{
+    namespace: string;
+    schemaId: string;
+    origin: "project_local" | "built_in";
+  }> | null;
+  candidateNamespaces: readonly string[];
+  rewrites: readonly ArgumentRewrite[];
+  undeclared: readonly UndeclaredArgument[];
+  repair: PredicateFactRepair | null;
+}>;
+
+function text(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() !== ""
+    ? value.trim()
+    : undefined;
+}
+
+function strings(value: unknown): string[] {
+  return Array.isArray(value)
+    ? value.filter((item): item is string => typeof item === "string")
+    : [];
+}
+
+function sourceField(entity: Entity): { source?: string } {
+  const source = text(entity.source);
+  return source !== undefined ? { source } : {};
+}
+
+function namespaceOf(entity: Entity): string {
+  return text(entity.predicate_namespace) ?? DEFAULT_NAMESPACE;
+}
+
+function signature(namespace: string, name: string, arity: number): string {
+  return `${namespace}:${name}/${arity}`;
+}
+
+function schemaRefs(facts: readonly Entity[]): Map<string, SchemaRef[]> {
+  const byName = new Map<string, SchemaRef[]>();
+  const add = (name: string, ref: SchemaRef) => {
+    byName.set(name, [...(byName.get(name) ?? []), ref]);
+  };
+  for (const entity of facts) {
+    if (entity.fact_kind !== "predicate_schema") continue;
+    const name = text(entity.predicate_name);
+    if (name === undefined) continue;
+    add(name, {
+      schemaId: String(entity.id),
+      namespace: namespaceOf(entity),
+      origin: "project_local",
+      argumentNames: strings(entity.argument_names),
+      entity,
+    });
+  }
+  // Built-in catalog schemas carry no namespace: facts that use them live in
+  // the default namespace. A project-local schema with the same signature wins.
+  for (const schema of BUILT_IN_PREDICATE_SCHEMAS) {
+    add(schema.predicate_name, {
+      schemaId: schema.id,
+      namespace: DEFAULT_NAMESPACE,
+      origin: "built_in",
+      argumentNames: schema.argument_names,
+    });
+  }
+  return byName;
+}
+
+function authoredProperties(entity: Entity): Record<string, unknown> {
+  // Keep only fields an upsert accepts. Query rows also carry relationship
+  // projections (relates_to, validates, ...) as strings or lists, which must
+  // never be replayed as entity properties.
+  return Object.fromEntries(
+    Object.entries(entity).filter(
+      ([key, value]) =>
+        AUTHORED_FIELDS.has(key) &&
+        !NON_AUTHORED_FIELDS.has(key) &&
+        value !== null &&
+        value !== undefined,
+    ),
+  );
+}
+
+function repairFor(
+  fact: Entity,
+  name: string,
+  args: readonly string[],
+  targetNamespace: string | null,
+  rewrites: readonly ArgumentRewrite[],
+): PredicateFactRepair {
+  const nextArgs = applyArgumentRewrites(args, rewrites);
+  const properties = authoredProperties(fact);
+  const previousKey = predicateCanonicalKey(name, args);
+  const nextKey = predicateCanonicalKey(name, nextArgs);
+  if (targetNamespace !== null)
+    properties.predicate_namespace = targetNamespace;
+  if (rewrites.length > 0) {
+    properties.predicate_args = nextArgs;
+    properties.canonical_key = nextKey;
+    if (properties.title === `Predicate: ${previousKey}`) {
+      properties.title = `Predicate: ${nextKey}`;
+    }
+  }
+  return { type: "fact", id: String(fact.id), properties };
+}
+
+/**
+ * Predicate facts must match a schema (project-local, or the built-in catalog
+ * in the default namespace) with the same namespace, name, and arity, and
+ * must use declared constants where the schema closes an argument.
+ */
+// implements REQ-kibi-predicate-schema-conformance
+export function evaluatePredicateSchemaConformance(
+  facts: readonly Entity[],
+): Violation[] {
+  const schemasByName = schemaRefs(facts);
+  const violations: Violation[] = [];
+
+  for (const schema of facts) {
+    if (schema.fact_kind !== "predicate_schema") continue;
+    const errors = predicateVocabularyErrors(schema);
+    if (errors.length === 0) continue;
+    violations.push({
+      rule: RULE,
+      entityId: String(schema.id),
+      description: `Predicate schema ${String(schema.id)} declares an invalid argument vocabulary: ${errors.join("; ")}`,
+      suggestion:
+        "Key argument_constants and argument_aliases by argument_names, and map every alias to a declared constant.",
+      ...sourceField(schema),
+      evidence: { schemaId: String(schema.id), errors },
+    });
+  }
+
+  for (const fact of facts) {
+    if (fact.fact_kind !== "predicate") continue;
+    const name = text(fact.predicate_name);
+    const args = strings(fact.predicate_args);
+    if (name === undefined || args.length === 0) continue;
+    const namespace = namespaceOf(fact);
+    const arity = args.length;
+    const sameShape = (schemasByName.get(name) ?? []).filter(
+      (ref) => ref.argumentNames.length === arity,
+    );
+    const exact =
+      sameShape.find(
+        (ref) => ref.namespace === namespace && ref.origin === "project_local",
+      ) ??
+      sameShape.find(
+        (ref) => ref.namespace === namespace && ref.origin === "built_in",
+      );
+    const candidates = [
+      ...new Map(
+        sameShape
+          .filter((ref) => ref.namespace !== namespace)
+          .map((ref) => [ref.namespace, ref]),
+      ).values(),
+    ];
+    const alignment =
+      exact === undefined && candidates.length === 1
+        ? candidates[0]
+        : undefined;
+    const schema = exact ?? alignment;
+    const conformance =
+      schema?.entity !== undefined
+        ? predicateArgumentConformance(
+            schema.argumentNames,
+            args,
+            predicateVocabularyFromEntity(schema.entity),
+          )
+        : { rewrites: [], undeclared: [] };
+
+    if (
+      exact !== undefined &&
+      conformance.rewrites.length === 0 &&
+      conformance.undeclared.length === 0
+    ) {
+      continue;
+    }
+
+    const issue: PredicateConformanceEvidence["issue"] =
+      exact === undefined
+        ? "missing_schema"
+        : conformance.undeclared.length > 0
+          ? "undeclared_constant"
+          : "alias_in_use";
+    const mechanical =
+      schema !== undefined && conformance.undeclared.length === 0;
+    const evidence: PredicateConformanceEvidence = {
+      factId: String(fact.id),
+      predicateName: name,
+      namespace,
+      arity,
+      issue,
+      schemaId: exact?.schemaId ?? null,
+      alignment:
+        alignment !== undefined
+          ? {
+              namespace: alignment.namespace,
+              schemaId: alignment.schemaId,
+              origin: alignment.origin,
+            }
+          : null,
+      candidateNamespaces: candidates.map((ref) => ref.namespace).sort(),
+      rewrites: conformance.rewrites,
+      undeclared: conformance.undeclared,
+      repair: mechanical
+        ? repairFor(
+            fact,
+            name,
+            args,
+            alignment?.namespace ?? null,
+            conformance.rewrites,
+          )
+        : null,
+    };
+    violations.push({
+      rule: RULE,
+      entityId: String(fact.id),
+      description: conformanceDescription(evidence),
+      suggestion: conformanceSuggestion(evidence),
+      ...sourceField(fact),
+      evidence,
+    });
+  }
+  return violations;
+}
+
+function conformanceDescription(
+  evidence: PredicateConformanceEvidence,
+): string {
+  const where = signature(
+    evidence.namespace,
+    evidence.predicateName,
+    evidence.arity,
+  );
+  const parts: string[] = [];
+  if (evidence.issue === "missing_schema") {
+    parts.push(
+      evidence.alignment !== null
+        ? `Predicate fact ${evidence.factId} uses ${where}, but its schema ${evidence.alignment.schemaId} is in namespace ${evidence.alignment.namespace}`
+        : evidence.candidateNamespaces.length > 1
+          ? `Predicate fact ${evidence.factId} uses ${where}; schemas with this signature exist in several namespaces (${evidence.candidateNamespaces.join(", ")})`
+          : `Predicate fact ${evidence.factId} uses ${where}, which has no predicate_schema`,
+    );
+  } else {
+    parts.push(`Predicate fact ${evidence.factId} (${where})`);
+  }
+  for (const rewrite of evidence.rewrites) {
+    parts.push(
+      `argument ${rewrite.argumentName} uses alias ${rewrite.from} for ${rewrite.to}`,
+    );
+  }
+  for (const value of evidence.undeclared) {
+    parts.push(
+      `argument ${value.argumentName} value ${value.value} is not a declared constant (${value.allowed.join(", ")})`,
+    );
+  }
+  return parts.join("; ");
+}
+
+function conformanceSuggestion(evidence: PredicateConformanceEvidence): string {
+  if (evidence.repair !== null) {
+    return "Mechanical repair available: review and apply it with kibi migrate --apply-safe (or replay the kb_upsert in the migration action).";
+  }
+  if (evidence.undeclared.length > 0) {
+    return "Use a declared constant, add the value to argument_constants, or map it with argument_aliases so kibi migrate can rewrite it.";
+  }
+  if (evidence.candidateNamespaces.length > 1) {
+    return "Set predicate_namespace to the schema this claim belongs to.";
+  }
+  return "Declare a predicate_schema for this signature (kb_suggest_predicates helps pick an existing one) or move the claim to a schema that already exists.";
+}
+
+/** Load every fact once and evaluate predicate conformance. */
+// implements REQ-kibi-predicate-schema-conformance
+export async function collectPredicateSchemaConformanceViolations(
+  prolog: Pick<PrologPort, "query">,
+): Promise<Violation[]> {
+  const facts = await loadEntitiesPaged(prolog, "fact");
+  return evaluatePredicateSchemaConformance(facts);
+}

package/src/public/operations/prolog-json.ts

@@ -62,12 +62,18 @@ export async function runOperationJsonQuery<T>(
   );
   // Loading a module and invoking its predicate in one interactive goal makes
   // SWI reject `use_module/1` under the engine's guarded `once/1` wrapper, so
-  // use two serialized requests for production and retain the combined goal
-  // only for the repository's Bun-based one-shot tests.
+  // an interactive port gets two serialized requests. That split is only
+  // sound when both requests reach the same live session: the engine daemon
+  // guarantees it by recycling a lost session with every loaded module
+  // restored, and a started PrologProcess fails loudly once its session is
+  // lost. Any port whose queries run in isolated processes (an unstarted or
+  // one-shot PrologProcess reports `oneShotMode`) must receive the combined
+  // goal, or the module load and the predicate call land in different SWI
+  // processes and the call fails with an existence error.
   const longLivedEngine =
     typeof (prolog as { storageStatus?: unknown }).storageStatus === "function";
   const oneShotMode =
-    prolog.oneShotMode === true ||
+    prolog.oneShotMode ??
     (!longLivedEngine &&
       process.env.NODE_ENV === "test" &&
       typeof (globalThis as { Bun?: unknown }).Bun !== "undefined");

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

@@ -50,9 +50,29 @@ export function failedEffectStatus(
   };
 }
 
+type EffectOutcome =
+  | { readonly kind: "completed" }
+  | { readonly kind: "failed"; readonly errorCode?: string }
+  | { readonly kind: "not_attempted" };
+
+function effectOutcome(
+  status: KibiResult["status"],
+  options: {
+    readonly attempted?: boolean;
+    readonly error?: KibiResult["error"];
+  },
+): EffectOutcome {
+  if (status !== "error") return { kind: "completed" };
+  if (options.attempted === false) return { kind: "not_attempted" };
+  return options.error
+    ? { kind: "failed", errorCode: options.error.code }
+    : { kind: "failed" };
+}
+
 function effectStatus(
   effect: OperationEffect,
   data: Record<string, unknown> | undefined,
+  outcome: EffectOutcome,
 ): KibiResult["effects"][number] {
   const failures = data?.effectFailures;
   if (Array.isArray(failures)) {
@@ -61,6 +81,25 @@ function effectStatus(
     );
     if (record(failure)) return failedEffectStatus(effect, failure);
   }
+  // A plan-only result declares the effects it left to a later call.
+  if (
+    Array.isArray(data?.skippedEffects) &&
+    data.skippedEffects.includes(effect)
+  ) {
+    return { kind: effect, status: "not_applicable" };
+  }
+  // An error envelope must never claim a declared effect completed: the
+  // operation either never ran or stopped before reporting its effects.
+  if (outcome.kind === "not_attempted") {
+    return { kind: effect, status: "not_applicable" };
+  }
+  if (outcome.kind === "failed") {
+    return {
+      kind: effect,
+      status: "failed",
+      ...(outcome.errorCode ? { errorCode: outcome.errorCode } : {}),
+    };
+  }
   return { kind: effect, status: "completed" };
 }
 
@@ -109,7 +148,14 @@ export function toKibiResult<T>(
   data: T,
   options: Partial<
     Pick<KibiResult<T>, "status" | "diagnostics" | "nextActions" | "error">
-  > = {},
+  > & {
+    /**
+     * False when the operation was rejected before it ran (invalid input),
+     * so an error envelope reports its effects as not applicable rather than
+     * failed.
+     */
+    readonly attempted?: boolean;
+  } = {},
 ): KibiResult<T> {
   const row = record(data) ? data : undefined;
   const status =
@@ -117,6 +163,7 @@ export function toKibiResult<T>(
     (row?.status === "committed_with_repairs"
       ? "committed_with_repairs"
       : "success");
+  const outcome = effectOutcome(status, options);
   return {
     kibiProtocol: KIBI_PROTOCOL_VERSION,
     operation: spec.name as OperationName,
@@ -124,7 +171,7 @@ export function toKibiResult<T>(
     status,
     data,
     effects: [
-      ...spec.effects.map((effect) => effectStatus(effect, row)),
+      ...spec.effects.map((effect) => effectStatus(effect, row, outcome)),
       ...extraFailedEffects(spec.effects, row),
     ],
     diagnostics: options.diagnostics ?? diagnostics(row?.diagnostics),
@@ -139,3 +186,68 @@ export function operationData(value: unknown): unknown {
   }
   return value;
 }
+
+// implements REQ-kibi-telemetry-remediation-evidence
+export interface NormalizedResultPayload {
+  /** The versioned KibiResult envelope, when the result carries one. */
+  readonly envelope?: Record<string, unknown>;
+  /** The operation payload that operation-specific telemetry fields read. */
+  readonly data?: Record<string, unknown>;
+}
+
+/**
+ * Resolve a tool result into its envelope and its operation payload.
+ *
+ * Callers hand results over in two shapes: MCP tool handlers pass the bare
+ * `toKibiResult` envelope, while some CLI and SDK routes wrap it as
+ * `{ structuredContent }`.  Deriving telemetry from the wrong shape silently
+ * yields an absent payload, so both shapes resolve here instead of at each
+ * call site.  An unresolvable payload stays `undefined` so callers can record
+ * the count as unknown rather than as zero.
+ */
+export function normalizeResultPayload(
+  result: unknown,
+): NormalizedResultPayload {
+  if (!record(result)) return {};
+  const candidate = record(result.structuredContent)
+    ? result.structuredContent
+    : result;
+  if (candidate.kibiProtocol !== KIBI_PROTOCOL_VERSION) {
+    return { data: candidate };
+  }
+  return {
+    envelope: candidate,
+    ...(record(candidate.data) ? { data: candidate.data } : {}),
+  };
+}
+
+function readPayloadCount(raw: unknown): number | null {
+  if (typeof raw === "number") return Number.isFinite(raw) ? raw : null;
+  // Some transports serialize counts as strings; an absent or unparseable
+  // value stays null so it is never coerced to a plausible zero.
+  if (typeof raw === "string" && raw.trim() !== "") {
+    const parsed = Number(raw);
+    return Number.isFinite(parsed) ? parsed : null;
+  }
+  return null;
+}
+
+/**
+ * Record a count that could not be read as unknown rather than as zero.
+ *
+ * A missing payload and an empty result are different facts, and collapsing
+ * them hides retrieval failures behind a plausible "0 results" row. Both the
+ * MCP and CLI diagnostic loggers derive counts here so the two surfaces stay
+ * at parity.
+ */
+export function appendPayloadCountField(
+  fields: Record<string, unknown>,
+  countKey: string,
+  noun: string,
+  payload: Record<string, unknown> | undefined,
+): void {
+  const count = readPayloadCount(payload?.count);
+  fields[countKey] = count;
+  fields.result_summary =
+    count === null ? `${noun} count unavailable` : `${count} ${noun}`;
+}

package/src/public/operations/runtime-types.ts

@@ -201,7 +201,7 @@ export type OperationContext = {
   readonly sourceFirst?: boolean;
   /** Internal apply-plan capability: source bytes were already approved/published. */
   readonly sourcePlanApplication?: boolean;
-  /** Internal apply-plan capability: caller holds the cooperative source lock. */
+  /** Internal operation capability: a parent operation holds the source lock. */
   readonly sourceMutationLockHeld?: boolean;
   readonly git?: GitPort;
   readonly net?: NetworkPort;

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

@@ -30,9 +30,16 @@ export const SELECTABLE_RULE_NAMES: readonly string[] = [
   "strict-readiness",
   "semantic-completeness",
   "proof-contract-symbols",
+  "entity-id-style",
+  "domain-redundancy",
+  "domain-implication",
+  "subject-key-identity",
+  "subject-key-shape",
+  "ontology-quality",
+  "predicate-schema-conformance",
 ];
 
 // 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, no-cycles, required-fields, deprecated-adr-no-successor, 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, proof-contract-symbols";
+  "must-priority-coverage, symbol-coverage, symbol-traceability, no-dangling-refs, source-relationship-parity, no-cycles, required-fields, deprecated-adr-no-successor, 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, proof-contract-symbols, entity-id-style, domain-redundancy, domain-implication, subject-key-identity, subject-key-shape, ontology-quality, predicate-schema-conformance";

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

@@ -41,7 +41,7 @@ export const querySpec = {
       id: {
         type: "string",
         description:
-          "Optional exact entity ID. Example: 'REQ-001'. If omitted, returns matching entities by other filters.",
+          "Optional exact entity ID. Example: 'REQ-cli-gc'. If omitted, returns matching entities by other filters.",
       },
       tags: {
         type: "array",
@@ -161,6 +161,13 @@ export const searchSpec = {
         description:
           "Intent-v1 acceptance threshold between 0 and 1. Low-confidence queries abstain instead of returning misleading matches.",
       },
+      fields: {
+        type: "string",
+        enum: ["summary", "full"],
+        default: "summary",
+        description:
+          "Optional result detail. 'summary' returns identifying metadata plus the match snippet for discovery. Use 'full' to include complete entity bodies, or follow up with kb_query for the exact entities you need.",
+      },
     },
   },
   requiresProlog: true,

package/src/public/operations/specs/mutation-schemas.ts

@@ -46,7 +46,7 @@ export const ENTITY_PROPERTIES_SCHEMA = {
     source: {
       type: "string",
       description:
-        "Optional provenance string. Example: 'docs/requirements/REQ-123.md'. Defaults to 'mcp://kibi/upsert'.",
+        "Optional provenance string. Example: '.kb/requirements/REQ-cli-gc.md'. Defaults to 'mcp://kibi/upsert'.",
     },
     tags: {
       type: "array",
@@ -69,7 +69,7 @@ export const ENTITY_PROPERTIES_SCHEMA = {
       type: "array",
       items: { type: "string" },
       description:
-        "Optional references. Example: ['REQ-010','https://example.com/spec'].",
+        "Optional references. Example: ['REQ-cli-gc','https://example.com/spec'].",
     },
     text_ref: {
       type: "string",
@@ -295,6 +295,25 @@ export const ENTITY_PROPERTIES_SCHEMA = {
       items: { type: "string" },
       description: "Optional ordered argument explanations.",
     },
+    argument_constants: {
+      type: "object",
+      additionalProperties: {
+        type: "array",
+        items: { type: "string", minLength: 1 },
+        minItems: 1,
+      },
+      description:
+        'predicate_schema only: allowed constants keyed by argument name, e.g. {"severity": ["warning", "info"]}. Predicate facts must use a listed constant for those arguments; unlisted arguments stay open.',
+    },
+    argument_aliases: {
+      type: "object",
+      additionalProperties: {
+        type: "object",
+        additionalProperties: { type: "string", minLength: 1 },
+      },
+      description:
+        'predicate_schema only: legacy spellings keyed by argument name, each mapped to a declared constant, e.g. {"severity": {"warn": "warning"}}. kibi migrate rewrites facts that still use an alias.',
+    },
     aliases: {
       type: "array",
       items: { type: "string" },
@@ -371,6 +390,7 @@ export const RELATIONSHIPS_SCHEMA = {
           "publishes",
           "consumes",
           "supersedes",
+          "restates",
           "relates_to",
         ],
         description:
@@ -383,7 +403,7 @@ export const RELATIONSHIPS_SCHEMA = {
       },
       to: {
         type: "string",
-        description: "Target entity ID (must exist). Example: 'REQ-001'.",
+        description: "Target entity ID (must exist). Example: 'REQ-cli-gc'.",
       },
     },
   },