rcf-lite 0.29.0 → 0.31.0

package/src/define/concern-catalogue.js

@@ -0,0 +1,130 @@
+// Concern catalogue (REQ-174 amendment paragraph; spec 2026-10-01
+// section 4 row "D5 catalogue", 0.30.0 PR 6).
+//
+// Eight concerns keyed by REQ shape. For every REQ in scope, D5's
+// crosscut:catalogue check enumerates the applicable (reqShape,
+// concern) pairs via this module and asserts a concern-ledger entry
+// keyed <REQ>:<concern> exists with disposition applied or waived (a
+// waived entry carries a reason).
+//
+// The catalogue is deliberately keyed on the concern name so a
+// shape-wise question like "what concerns apply to this REQ?" is a
+// filter against one map, not a scan across eight. The reverse view
+// (which shape triggers which concern) is a transpose and lives in
+// applicableConcernsFor().
+//
+// Keys share names with the baseline catalogue
+// (packages/rcf-lite/src/core/baseline-catalog) where names coincide:
+// `auth` is the only name the two share today (the baseline-AC
+// catalogue has no per-concern crosscut keys yet). The gate reader
+// composes the ledger key as `<REQ>:<concern>`, so no key translation
+// is needed between the two surfaces.
+//
+// Pure: no I/O, no state, no time. The export is frozen at module
+// load so a consumer cannot mutate the shared source.
+
+/**
+ * Canonical ordering of concern names (spec section 4 row 'D5
+ * catalogue'). Readers that iterate the catalogue use this so display
+ * order stays stable.
+ *
+ * @type {ReadonlyArray<string>}
+ */
+export const CONCERN_KEYS = Object.freeze([
+  'auth',
+  'errorEnvelope',
+  'loggingAudit',
+  'retention',
+  'performance',
+  'secrets',
+  'timeAndTimezone',
+  'concurrencyIdempotency',
+]);
+
+/**
+ * The eight REQ shapes the catalogue reasons over. These are the
+ * values a REQ's shapeClassification.shapes array may carry; a REQ
+ * may carry more than one. `other` is the catch-all whose only
+ * applicable concern today is none.
+ *
+ * @type {ReadonlyArray<string>}
+ */
+export const REQ_SHAPES = Object.freeze([
+  'auth',
+  'httpApi',
+  'cliCommand',
+  'persistence',
+  'batch',
+  'externalIntegration',
+  'webUi',
+  'other',
+]);
+
+/**
+ * Shape set helper. The `loggingAudit` row below reads "every shape
+ * but other"; expressing that once beats enumerating the seven
+ * concrete shapes.
+ */
+const ALL_BUT_OTHER = Object.freeze(REQ_SHAPES.filter((s) => s !== 'other'));
+
+/**
+ * Per-concern applicability map keyed by concern name (spec section 4
+ * row 'D5 catalogue', verbatim):
+ *
+ *   auth                   -> auth, httpApi
+ *   errorEnvelope          -> httpApi, cliCommand
+ *   loggingAudit           -> every REQ shape but other
+ *   retention              -> persistence
+ *   performance            -> httpApi, batch
+ *   secrets                -> auth, externalIntegration
+ *   timeAndTimezone        -> persistence, batch
+ *   concurrencyIdempotency -> httpApi, persistence
+ *
+ * @type {Readonly<Record<string, ReadonlyArray<string>>>}
+ */
+export const CONCERN_APPLICABILITY = Object.freeze({
+  auth: Object.freeze(['auth', 'httpApi']),
+  errorEnvelope: Object.freeze(['httpApi', 'cliCommand']),
+  loggingAudit: ALL_BUT_OTHER,
+  retention: Object.freeze(['persistence']),
+  performance: Object.freeze(['httpApi', 'batch']),
+  secrets: Object.freeze(['auth', 'externalIntegration']),
+  timeAndTimezone: Object.freeze(['persistence', 'batch']),
+  concurrencyIdempotency: Object.freeze(['httpApi', 'persistence']),
+});
+
+/**
+ * Which concerns apply to a REQ shape. Reads the per-concern map
+ * once and returns the names, in CONCERN_KEYS order, whose shape set
+ * contains the input. An unknown shape returns [].
+ *
+ * @param {string} reqShape
+ * @returns {string[]}
+ */
+export function applicableConcernsFor(reqShape) {
+  if (typeof reqShape !== 'string' || reqShape.length === 0) return [];
+  const out = [];
+  for (const concern of CONCERN_KEYS) {
+    const shapes = CONCERN_APPLICABILITY[concern];
+    if (shapes && shapes.includes(reqShape)) out.push(concern);
+  }
+  return out;
+}
+
+/**
+ * Union of applicable concerns across a set of REQ shapes. A REQ
+ * carries an array of shapes (shapeClassification.shapes); the
+ * applicable concerns for that REQ are the union of applicableConcerns
+ * for each shape, in CONCERN_KEYS order with no duplicates.
+ *
+ * @param {Iterable<string>} shapes
+ * @returns {string[]}
+ */
+export function applicableConcernsForShapes(shapes) {
+  const seen = new Set();
+  for (const shape of shapes ?? []) {
+    for (const c of applicableConcernsFor(shape)) seen.add(c);
+  }
+  // Preserve canonical order.
+  return CONCERN_KEYS.filter((c) => seen.has(c));
+}

package/src/define/freeze-record.js

@@ -44,6 +44,8 @@
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 
+import { computeTreeHash } from '../query/delta.js';
+
 /**
  * Relative path (under the project root) of the freeze record. Used by
  * the walker-invisibility invariant test and by every caller that
@@ -245,3 +247,75 @@ export async function saveFreezeRecord({ projectRoot, record }) {
   await writeFile(filePath, `${JSON.stringify(validated, null, 2)}\n`, 'utf8');
   return { filePath };
 }
+
+/**
+ * Apply `freeze.override { reason, by, at }` to the project's freeze
+ * record and persist it (0.30.0 PR 8, REQ-177 / TAC-4125). When no
+ * freeze record exists, a minimal placeholder is created so the
+ * override has a home: `frozenAt = at`, `treeHash` from the live tree
+ * via computeTreeHash on the supplied `docHashes` (passed by the
+ * caller so this module stays pure of walker I/O), `briefStatements`
+ * from the caller (defaults to 0 when the brief ledger is absent).
+ * On an existing record the override is set in place and every other
+ * field is preserved.
+ *
+ * The writer validates through saveFreezeRecord so the on-disk schema
+ * stays canonical. A missing-non-empty reason throws before any write.
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @param {string} args.reason - operator-supplied non-empty reason string.
+ * @param {string} args.by - author identity recorded on the override.
+ * @param {string} args.at - ISO-8601 timestamp.
+ * @param {Record<string, string>} [args.docHashes] - the live tree's docHashes map; used only when no prior record exists so a minimal record can be stamped.
+ * @param {string} [args.treeHash] - the live tree hash; used only when no prior record exists.
+ * @param {number} [args.briefStatements] - brief ledger high-water mark; used only when no prior record exists.
+ * @returns {Promise<{ filePath: string, record: import('../query/delta.js').FreezeRecord & Record<string, unknown> }>}
+ */
+export async function applyOverrideToFreezeRecord({
+  projectRoot,
+  reason,
+  by,
+  at,
+  docHashes = {},
+  treeHash = null,
+  briefStatements = 0,
+}) {
+  if (typeof reason !== 'string' || reason.length === 0) {
+    throw new FreezeRecordError(
+      "applyOverrideToFreezeRecord: 'reason' must be a non-empty string.",
+      { filePath: FREEZE_RECORD_REL_PATH, field: 'override.reason' },
+    );
+  }
+  if (typeof by !== 'string' || by.length === 0) {
+    throw new FreezeRecordError(
+      "applyOverrideToFreezeRecord: 'by' must be a non-empty string.",
+      { filePath: FREEZE_RECORD_REL_PATH, field: 'override.by' },
+    );
+  }
+  if (typeof at !== 'string' || at.length === 0) {
+    throw new FreezeRecordError(
+      "applyOverrideToFreezeRecord: 'at' must be a non-empty string.",
+      { filePath: FREEZE_RECORD_REL_PATH, field: 'override.at' },
+    );
+  }
+  const existing = await loadFreezeRecord({ projectRoot });
+  // On an unfrozen tree, mint a minimal record whose treeHash is the
+  // live tree hash computed from the caller-supplied docHashes map,
+  // so the override is attached to a verifiable snapshot rather than a
+  // placeholder. Callers (the build CLI) pass computeDelta's
+  // currentDocHashes so the hash agrees with the delta model.
+  const computedTreeHash = treeHash ?? computeTreeHash(docHashes);
+  /** @type {import('../query/delta.js').FreezeRecord & Record<string, unknown>} */
+  const record = existing
+    ? { ...existing, override: { reason, by, at } }
+    : {
+      frozenAt: at,
+      treeHash: computedTreeHash,
+      docHashes: { ...docHashes },
+      briefStatements,
+      override: { reason, by, at },
+    };
+  const { filePath } = await saveFreezeRecord({ projectRoot, record });
+  return { filePath, record };
+}

package/src/define/ledgers.js

@@ -102,7 +102,7 @@ export class LedgerError extends Error {
    * @param {string} message
    * @param {object} [opts]
    * @param {string} [opts.filePath]
-   * @param {'parseFailure' | 'schemaFailure' | 'ioFailure' | 'usage'} [opts.code]
+   * @param {'parseFailure' | 'schemaFailure' | 'ioFailure' | 'usage' | 'conflict'} [opts.code]
    * @param {string} [opts.field]
    */
   constructor(message, opts = {}) {
@@ -390,26 +390,105 @@ export function nextIdFor(name, body) {
  * updated body. Pure over its inputs (does not write to disk); the
  * CLI calls `saveLedger` with the result.
  *
+ * Ruling R1 2026-10-05 (w-2026-10-05-dave-001): `add` is idempotent by
+ * id. When `args.id` is set (the harness carries it on a replayed
+ * turn):
+ *   - no entry with that id exists: honour the override and add the
+ *     entry at that id (any gaps in the id sequence are legal; the
+ *     per-ledger validator enforces uniqueness, not contiguity);
+ *   - entry with that id exists and the content matches: return
+ *     `{ status: 'unchanged', body, entry }`, no new write;
+ *   - entry with that id exists and the content differs: throw a
+ *     `LedgerError` (code 'conflict') naming the id and the differing
+ *     field keys so the CLI exits 3. Update is a separate verb.
+ * When `args.id` is omitted the next id is minted as before (the
+ * pre-R1 behaviour; a replayed turn without a carried id still works
+ * but duplicates the entry at a new id, which is why the harness is
+ * responsible for threading --id back).
+ *
  * @param {object} args
  * @param {LedgerName} args.name
  * @param {Record<string, unknown[]>} args.body
  * @param {Record<string, unknown>} args.entry - fields other than id / addedAt / status
+ * @param {number} [args.id] - optional id override (R1)
  * @param {string} [args.now] - ISO timestamp; defaults to Date.now()
- * @returns {{ body: Record<string, unknown[]>, entry: Record<string, unknown> }}
+ * @returns {{ body: Record<string, unknown[]>, entry: Record<string, unknown>, status?: 'added' | 'unchanged' }}
  */
-export function addEntry({ name, body, entry, now }) {
+export function addEntry({ name, body, entry, id, now }) {
   const cfg = LEDGER_CONFIG[name];
   if (!cfg) throw new LedgerError(`Unknown ledger '${name}'.`, { code: 'usage' });
-  const id = nextIdFor(name, body);
+  const list = /** @type {any[]} */ (body[cfg.arrayKey] ?? []);
+  let resolvedId;
+  if (id !== undefined) {
+    if (!Number.isInteger(id) || id < 1) {
+      throw new LedgerError(`${name} add --id must be a positive integer, got ${id}.`, {
+        filePath: ledgerRelPath(name), field: 'id', code: 'usage',
+      });
+    }
+    const existing = list.find((e) => Number(e?.id) === Number(id));
+    if (existing) {
+      // R1 idempotency check: compare caller-supplied fields against the
+      // existing entry. `addedAt` and `status` default on first add, so
+      // they are compared only when the caller explicitly supplied them.
+      const differing = [];
+      for (const [key, value] of Object.entries(entry)) {
+        if (value === undefined) continue;
+        if (key === 'id') continue;
+        if (key === 'addedAt' || key === 'status') {
+          // Default values auto-populated on first add; skip unless the
+          // caller passed them explicitly AND they differ.
+          if (existing[key] !== value) differing.push(key);
+          continue;
+        }
+        if (!deepEqual(existing[key], value)) differing.push(key);
+      }
+      if (differing.length === 0) {
+        return { body, entry: existing, status: 'unchanged' };
+      }
+      throw new LedgerError(
+        `${name} ledger entry ${id} already exists with different content; differing fields: ${differing.sort().join(', ')}. Use the update verb to patch.`,
+        { filePath: ledgerRelPath(name), field: `id ${id}`, code: 'conflict' },
+      );
+    }
+    resolvedId = id;
+  } else {
+    resolvedId = nextIdFor(name, body);
+  }
   const full = {
-    id,
+    id: resolvedId,
     ...entry,
     addedAt: entry.addedAt ?? now ?? new Date().toISOString(),
     status: entry.status ?? 'open',
   };
-  const nextBody = { ...body, [cfg.arrayKey]: [...(body[cfg.arrayKey] ?? []), full] };
+  const nextBody = { ...body, [cfg.arrayKey]: [...list, full] };
   validateLedger(name, nextBody, ledgerRelPath(name));
-  return { body: nextBody, entry: full };
+  return { body: nextBody, entry: full, status: 'added' };
+}
+
+/**
+ * Deep-equality over JSON-shaped values. Used by R1's idempotency
+ * check to compare a caller-supplied field against the existing entry.
+ * Arrays and plain objects are compared structurally; primitives via
+ * Object.is. Pure.
+ */
+function deepEqual(a, b) {
+  if (Object.is(a, b)) return true;
+  if (a === null || b === null) return false;
+  if (typeof a !== typeof b) return false;
+  if (Array.isArray(a)) {
+    if (!Array.isArray(b) || a.length !== b.length) return false;
+    for (let i = 0; i < a.length; i += 1) if (!deepEqual(a[i], b[i])) return false;
+    return true;
+  }
+  if (typeof a === 'object') {
+    if (typeof b !== 'object' || Array.isArray(b)) return false;
+    const ak = Object.keys(a);
+    const bk = Object.keys(b);
+    if (ak.length !== bk.length) return false;
+    for (const k of ak) if (!deepEqual(a[k], b[k])) return false;
+    return true;
+  }
+  return false;
 }
 
 /**

package/src/define/probe-runner.js

@@ -0,0 +1,55 @@
+// Probe runner seam (REQ-175; spec 2026-10-01 section 4 row 'D6 scans
+// and the injectable probe runner' and section 11.6; ADR-4131 extended
+// by DEFINE step 3 PR 7).
+//
+// A probeRunner is `({ reqId, tree }) => findings[]` where each
+// finding is `{ reqId, finding, severity?, hash?, status? }`. The
+// shape mirrors a probe-ledger entry minus the ids and timestamps
+// computeReadiness assigns when it merges the findings into the probe
+// ledger it hands the gate.
+//
+// IMPORTANT: NO RUNNER SHIPS. rcf-lite has no LLM at runtime and does
+// not spawn processes or make network calls. The harness is the
+// runner: it either calls `ledger probes add` directly, or it drives a
+// test invocation that passes a stub runner into computeReadiness. The
+// seam exists so a test harness or a future harness-driven call site
+// has one named extension point rather than monkey-patching the
+// probe-ledger reader.
+//
+// Shape alone; the function stays as a type-level reference and is not
+// invoked by the CLI today.
+
+/**
+ * @typedef {{
+ *   reqId: string,
+ *   finding: string,
+ *   severity?: 'low' | 'medium' | 'high',
+ *   hash?: string,
+ *   status?: 'open' | 'closed' | 'attested',
+ * }} ProbeFinding
+ */
+
+/**
+ * @typedef {(args: { reqId: string, tree: unknown }) => ProbeFinding[]} ProbeRunner
+ */
+
+/**
+ * The default "no runner" sentinel. computeReadiness treats a null or
+ * absent runner as "do not inject findings"; its result then equals
+ * the 0.29.0 result on the same fixture (AC-17504-2).
+ *
+ * @type {ProbeRunner | null}
+ */
+export const NO_PROBE_RUNNER = null;
+
+/**
+ * Guard that a value is a usable probeRunner function. Pure. Exported
+ * so computeReadiness can skip injection cleanly on a non-function
+ * (`undefined`, `null`, or a mis-typed value) without throwing.
+ *
+ * @param {unknown} value
+ * @returns {value is ProbeRunner}
+ */
+export function isProbeRunner(value) {
+  return typeof value === 'function';
+}

package/src/define/validate-findings.js

@@ -0,0 +1,256 @@
+// `rcf define validate` finding set (0.30.0 PR 8; REQ-178 / TAC-4126).
+//
+// Four new findings over the walker's schema and broken-reference pass:
+//
+//   - interface kind outside INTERFACE_KINDS (spec section 4 validate
+//     row; AC-17802-1).
+//   - bracketed AC class prefix outside the five known classes (spec
+//     section 4 validate row; AC-17802-2). An AC description with NO
+//     leading bracketed prefix is NOT a finding (decision 10, kept).
+//   - tacIds naming a non-TAC (spec section 4 validate row).
+//   - ownerRef or deliveredBy that does not resolve on the walker tree
+//     (spec section 4 validate row).
+//
+// Pure over the walker tree model: no filesystem I/O; the caller
+// (src/cli/validate.js) merges the returned entries into the `errors`
+// array it already exits on (exit 3), so --json and the text report
+// render these exactly as a schema or broken-reference error does.
+//
+// Shape of each finding (matches rcfError shape consumed by
+// formatErrors): { kind: 'defineValidate', rule, documentId, filePath,
+// field, message }. `rule` fixes the class so a caller can match on
+// one of five constants rather than a message substring.
+//
+// Decision 10 is binding: a validate finding for a missing class
+// marker would fail the dogfood tree and every legacy tree's CI; D4
+// reports absence as the floor already.
+
+import { INTERFACE_KINDS, resolveOwnerRefField } from '../query/gates.js';
+
+/** @typedef {{ kind: 'defineValidate', rule: string, documentId: string|null, filePath: string|null, field: string|null, message: string }} DefineValidateFinding */
+
+const INTERFACE_KINDS_SET = new Set(INTERFACE_KINDS);
+/** Known AC-class prefix set (same source of truth as src/query/gates.js). */
+const KNOWN_AC_CLASSES = new Set(['happy', 'edge', 'failure', 'must-not', 'non-functional']);
+/** Leading bracketed prefix on an AC description. */
+const BRACKET_PREFIX_RE = /^\[([^\]]+)\]/;
+
+/**
+ * Collect PR 8 define-validate findings from a walker tree model.
+ *
+ * @param {object} tree - walker tree.
+ * @returns {DefineValidateFinding[]}
+ */
+export function collectDefineValidateFindings(tree) {
+  /** @type {DefineValidateFinding[]} */
+  const findings = [];
+  const tacIds = new Set();
+  for (const tac of tree.tacs ?? []) {
+    if (tac && typeof tac.tacId === 'string') tacIds.add(tac.tacId);
+  }
+  const allIds = tree.byId instanceof Map ? new Set(tree.byId.keys()) : new Set();
+
+  // 1. Interface kinds outside the vocabulary.
+  for (const tac of tree.tacs ?? []) {
+    const interfaces = Array.isArray(tac.interfaces) ? tac.interfaces : [];
+    for (const iface of interfaces) {
+      const kind = iface?.kind;
+      if (typeof kind === 'string' && INTERFACE_KINDS_SET.has(kind)) continue;
+      // Only emit a finding when `kind` is a string (walker schema
+      // already covers absent / non-string with its own error).
+      if (typeof kind !== 'string') continue;
+      findings.push({
+        kind: 'defineValidate',
+        rule: 'defineValidate:interfaceKind',
+        documentId: tac.tacId ?? null,
+        filePath: null,
+        field: `interfaces[${iface?.name ?? '?'}].kind`,
+        message: `define validate: interface kind ${JSON.stringify(kind)} on ${tac.tacId}:${iface?.name ?? '(unnamed)'} is outside the closed vocabulary ${JSON.stringify([...INTERFACE_KINDS])}`,
+      });
+    }
+  }
+
+  // 2. AC class prefix outside the known classes. Absence is NOT a
+  // finding (decision 10). Iterate every US's inline AC array.
+  for (const us of tree.userStories ?? []) {
+    const acs = Array.isArray(us.acceptanceCriteria) ? us.acceptanceCriteria : [];
+    for (const ac of acs) {
+      const desc = typeof ac?.description === 'string' ? ac.description : '';
+      const m = desc.match(BRACKET_PREFIX_RE);
+      if (!m) continue;
+      const prefix = m[1].trim();
+      if (KNOWN_AC_CLASSES.has(prefix)) continue;
+      findings.push({
+        kind: 'defineValidate',
+        rule: 'defineValidate:acClassPrefix',
+        documentId: ac?.id ?? us?.usId ?? null,
+        filePath: null,
+        field: 'description',
+        message: `define validate: AC ${ac?.id ?? '(unknown id)'} on ${us?.usId ?? '(unknown story)'} starts with bracketed prefix [${prefix}] which is not one of {happy, edge, failure, must-not, non-functional}`,
+      });
+    }
+  }
+
+  // 3. tacIds on a US naming a non-TAC.
+  for (const us of tree.userStories ?? []) {
+    const ids = Array.isArray(us.tacIds) ? us.tacIds : [];
+    for (const id of ids) {
+      if (typeof id !== 'string') continue;
+      if (tacIds.has(id)) continue;
+      findings.push({
+        kind: 'defineValidate',
+        rule: 'defineValidate:tacIdsResolves',
+        documentId: us.usId ?? null,
+        filePath: null,
+        field: 'tacIds',
+        message: `define validate: US ${us.usId ?? '(unknown)'} tacIds entry ${JSON.stringify(id)} does not resolve to any TAC on the tree`,
+      });
+    }
+  }
+
+  // 4a. ownerRef on an AC that does not resolve under R11 grammar on
+  //     the named TAC or ADR (spec section 17, 2026-10-03). The
+  //     `resolveOwnerRefField` helper accepts `interfaces[<name>]`,
+  //     `responsibilities[<n>]`, `dependencies[<name>]`,
+  //     `alternativesConsidered[<n>]` and bare schema fields
+  //     (`purpose`, `internalStructure`, `decision`, etc.). Dotted
+  //     forms are refused: the finding message names the field so
+  //     the author can rewrite to bracket grammar.
+  const tacByIdLocal = new Map();
+  for (const tac of tree.tacs ?? []) {
+    if (tac?.tacId) tacByIdLocal.set(tac.tacId, tac);
+  }
+  const adrByIdLocal = new Map();
+  for (const adr of tree.adrs ?? []) {
+    if (adr?.adrId) adrByIdLocal.set(adr.adrId, adr);
+  }
+  for (const us of tree.userStories ?? []) {
+    const acs = Array.isArray(us.acceptanceCriteria) ? us.acceptanceCriteria : [];
+    for (const ac of acs) {
+      const ref = ac?.ownerRef;
+      if (!ref || typeof ref !== 'object') continue;
+      const tacId = typeof ref.tacId === 'string' ? ref.tacId : null;
+      const adrId = typeof ref.adrId === 'string' ? ref.adrId : null;
+      const field = typeof ref.field === 'string' ? ref.field : null;
+      if ((!tacId && !adrId) || !field) continue;
+      let owner = null;
+      let ownerLabel = null;
+      if (tacId) {
+        owner = tacByIdLocal.get(tacId) ?? null;
+        ownerLabel = tacId;
+        if (!owner) {
+          findings.push({
+            kind: 'defineValidate',
+            rule: 'defineValidate:ownerRefResolves',
+            documentId: ac?.id ?? us?.usId ?? null,
+            filePath: null,
+            field: 'ownerRef',
+            message: `define validate: AC ${ac?.id ?? '(unknown)'} ownerRef names TAC ${JSON.stringify(tacId)} which is not on the tree`,
+          });
+          continue;
+        }
+      } else if (adrId) {
+        owner = adrByIdLocal.get(adrId) ?? null;
+        ownerLabel = adrId;
+        if (!owner) {
+          findings.push({
+            kind: 'defineValidate',
+            rule: 'defineValidate:ownerRefResolves',
+            documentId: ac?.id ?? us?.usId ?? null,
+            filePath: null,
+            field: 'ownerRef',
+            message: `define validate: AC ${ac?.id ?? '(unknown)'} ownerRef names ADR ${JSON.stringify(adrId)} which is not on the tree`,
+          });
+          continue;
+        }
+      }
+      if (!resolveOwnerRefField(owner, field)) {
+        findings.push({
+          kind: 'defineValidate',
+          rule: 'defineValidate:ownerRefResolves',
+          documentId: ac?.id ?? us?.usId ?? null,
+          filePath: null,
+          field: 'ownerRef',
+          message: `define validate: AC ${ac?.id ?? '(unknown)'} ownerRef.field ${JSON.stringify(field)} does not resolve on ${ownerLabel} under R11 grammar (bracket forms: interfaces[<name>], responsibilities[<n>], dependencies[<name>], alternativesConsidered[<n>]; or a bare schema field name)`,
+        });
+      }
+    }
+  }
+
+  // 4b. deliveredBy on a REQ. Two forms are accepted by the schema:
+  //     (i) a legacy string that must resolve to any id in the tree
+  //     (back-compat for pre-DEFINE REQs; the walker's own schema
+  //     check has long since been dropped so no production REQ should
+  //     carry a bare string, but this path remains defensive);
+  //     (ii) the object form `{ tacId | adrId, field }` which R11
+  //     resolves under the same grammar as `ownerRef`. The object
+  //     form was silently skipped before PR 9 (review 2026-10-03).
+  for (const req of tree.requirements ?? []) {
+    const d = req?.deliveredBy;
+    if (typeof d === 'string' && d.length > 0) {
+      if (!allIds.has(d)) {
+        findings.push({
+          kind: 'defineValidate',
+          rule: 'defineValidate:deliveredByResolves',
+          documentId: req.reqId ?? null,
+          filePath: null,
+          field: 'deliveredBy',
+          message: `define validate: REQ ${req.reqId ?? '(unknown)'} deliveredBy ${JSON.stringify(d)} does not resolve to any document on the tree`,
+        });
+      }
+      continue;
+    }
+    if (!d || typeof d !== 'object') continue;
+    const tacId = typeof d.tacId === 'string' ? d.tacId : null;
+    const adrId = typeof d.adrId === 'string' ? d.adrId : null;
+    const field = typeof d.field === 'string' ? d.field : null;
+    if (!tacId && !adrId) continue;
+    let owner = null;
+    let ownerLabel = null;
+    if (tacId) {
+      owner = tacByIdLocal.get(tacId) ?? null;
+      ownerLabel = tacId;
+      if (!owner) {
+        findings.push({
+          kind: 'defineValidate',
+          rule: 'defineValidate:deliveredByResolves',
+          documentId: req.reqId ?? null,
+          filePath: null,
+          field: 'deliveredBy',
+          message: `define validate: REQ ${req.reqId ?? '(unknown)'} deliveredBy names TAC ${JSON.stringify(tacId)} which is not on the tree`,
+        });
+        continue;
+      }
+    } else if (adrId) {
+      owner = adrByIdLocal.get(adrId) ?? null;
+      ownerLabel = adrId;
+      if (!owner) {
+        findings.push({
+          kind: 'defineValidate',
+          rule: 'defineValidate:deliveredByResolves',
+          documentId: req.reqId ?? null,
+          filePath: null,
+          field: 'deliveredBy',
+          message: `define validate: REQ ${req.reqId ?? '(unknown)'} deliveredBy names ADR ${JSON.stringify(adrId)} which is not on the tree`,
+        });
+        continue;
+      }
+    }
+    // `field` is schema-optional on deliveredBy; a REQ whose
+    // deliveredBy carries only a tacId/adrId with no field names the
+    // whole owner and resolves by presence of the owner alone.
+    if (!field) continue;
+    if (!resolveOwnerRefField(owner, field)) {
+      findings.push({
+        kind: 'defineValidate',
+        rule: 'defineValidate:deliveredByResolves',
+        documentId: req.reqId ?? null,
+        filePath: null,
+        field: 'deliveredBy',
+        message: `define validate: REQ ${req.reqId ?? '(unknown)'} deliveredBy.field ${JSON.stringify(field)} does not resolve on ${ownerLabel} under R11 grammar (bracket forms: interfaces[<name>], responsibilities[<n>], dependencies[<name>], alternativesConsidered[<n>]; or a bare schema field name)`,
+      });
+    }
+  }
+
+  return findings;
+}

package/src/mcp/tools.js

@@ -639,7 +639,7 @@ const DEFINITIONS = [
       properties: {
         kind: { type: 'string', enum: KIND_ENUM, description: 'Document kind' },
         parent: { type: 'string', description: 'Parent document id; required for every kind except cn (which has no parent)' },
-        id: { type: 'string', description: 'Override the auto-assigned id (refuses on collision)' },
+        id: { type: 'string', description: 'Override the auto-assigned id. Idempotent by id: an existing id with identical content is a no-op; different content refuses as a conflict naming the differing fields (use rcf_update to patch)' },
         title: { type: 'string', description: 'Required for req / us / tac / adr / fbs / ts' },
         description: { type: 'string', description: 'Required for ac / tc' },
         purpose: { type: 'string', description: 'Required for ts' },