rcf-lite 0.30.0 → 0.32.0

package/src/cli/create.js

@@ -64,8 +64,11 @@ Options:
                             every non-root child carries a mandatory
                             parentId-style field). See the parent table
                             above for which id each kind expects.
-  --id <id>                 Override auto-assigned id (refuses on
-                            collision)
+  --id <id>                 Override auto-assigned id. Idempotent by id:
+                            an existing id with identical content is a
+                            no-op ('<id>: unchanged', exit 0); with
+                            different content it refuses (exit 3, names
+                            the differing fields). Use update to patch
   --title <string>          Required for req / us / tac / adr / fbs / ts
                             (ac / tc use --description)
   --description <string>    Body description; required for ac / tc
@@ -297,6 +300,15 @@ export async function main(argv, deps = {}) {
   if (isRcfError(result)) {
     return handleWriterError(result, stderr);
   }
+  // Ruling R1 extension 2026-10-05 (PR 292 follow-up, w-2026-10-05-dave-013):
+  // a same-id replay with identical content exits 0 with 'unchanged';
+  // the file is not rewritten. Mirrors `rcf define ledger add --id`.
+  if (result.status === 'unchanged') {
+    if (!flags.quiet) {
+      stdout.write(`${result.id}: unchanged (${result.filePath})\n`);
+    }
+    return 0;
+  }
   if (options.dryRun) {
     if (!flags.quiet) stdout.write(`[dry-run] would create ${result.id} at ${result.filePath}\n`);
     return 0;
@@ -358,6 +370,10 @@ const ERROR_KINDS = new Set([
   'parseFailure',
   'ioFailure',
   'usage',
+  // Ruling R1 extension 2026-10-05 (PR 292 follow-up): a same-id
+  // create whose would-be body differs from the existing doc refuses
+  // with `kind: 'conflict'` and exits 3 (never silently overwrites).
+  'conflict',
 ]);
 
 function isRcfError(value) {
@@ -412,6 +428,10 @@ function handleWriterError(err, stderr) {
   stderr.write(`[error] ${kind} ${err.message}\n`);
   if (kind === 'usage') return 2;
   if (kind === 'validation' || kind === 'brokenReference') return 3;
+  // Ruling R1 extension 2026-10-05 (PR 292 follow-up): a same-id
+  // create with different content refuses with exit 3; `update` is
+  // the verb for patching.
+  if (kind === 'conflict') return 3;
   if (kind === 'missingFile' || kind === 'parseFailure') return 2;
   return 1;
 }

package/src/cli/freeze.js

@@ -35,6 +35,7 @@ import { checkCodeNodeResolution } from '#core/store';
 import { findProjectRoot } from '../view/index.js';
 import { loadFreezeRecord, saveFreezeRecord } from '../define/freeze-record.js';
 import { loadAllLedgers } from '../define/ledgers.js';
+import { resolveInterfacePaths } from '../define/interface-paths.js';
 import {
   STAGE_ALIASES,
   STAGE_GATES,
@@ -368,6 +369,12 @@ async function runFreeze({
   // freezeableAfterAck check below is the real gate (freeze still
   // exits 4 on an unfrozen tree); the wrap's refusal is informational
   // here as it is on readiness.
+  // Issue 302 (2026-10-06): freeze now pre-resolves the TAC
+  // interface `path:` tokens the way readiness does, so the D3
+  // `shapes:pathsResolve` check inside freeze agrees with the
+  // readiness verdict instead of defaulting to an empty set and
+  // false-failing resolvable paths.
+  const resolvedPaths = await resolveInterfacePaths(projectRoot, tree);
   /** @type {import('../query/readiness.js').ReadinessResult} */
   const readiness = computeReadiness(tree, {
     freeze: freezeForCompute,
@@ -375,6 +382,7 @@ async function runFreeze({
     profileText,
     testPointers,
     validateErrors,
+    resolvedPaths,
   });
   const gated = await runWithAdmissibilityGate({
     tree,

package/src/cli/ledger.js

@@ -27,6 +27,7 @@ import { runIntakeScansOnDelta } from '../intake/orchestrator.js';
 import { findProjectRoot } from '../view/index.js';
 
 const OPTION_SPEC = {
+  id: { type: 'string' },
   kind: { type: 'string' },
   text: { type: 'string' },
   from: { type: 'string' },
@@ -74,6 +75,15 @@ Common flags:
   --help                    Print this help
 
 brief add flags:
+  --id <n>                  Optional positive integer. When set, the add
+                            is idempotent by id (ruling R1 2026-10-05):
+                            an entry at that id with identical content
+                            exits 0 printing 'unchanged' (--json emits
+                            {status:"unchanged",id:n}); different content
+                            at the same id exits 3 naming the differing
+                            fields; a free id is honoured as the override.
+                            The harness carries --id back when it replays
+                            a turn so the add is a no-op on replay.
   --kind <${BRIEF_KINDS.join('|')}>
                             Statement kind (default: capability)
   --text <text>             The statement text (mutually exclusive with --from)
@@ -193,6 +203,14 @@ export async function main(argv, deps = {}) {
     return await runResolve({ projectRoot, name, positionals, flags, stdout, stderr });
   } catch (err) {
     if (err instanceof LedgerError) {
+      // Ruling R1 2026-10-05: a same-id-different-content refusal
+      // exits 3 (not 1 and not 2) so a replaying harness can
+      // distinguish 'you tried to overwrite a prior answer' from a
+      // schema failure or a usage error. Update is the verb for that.
+      if (err.code === 'conflict') {
+        stderr.write(`[error] ledger: ${err.message}\n`);
+        return 3;
+      }
       stderr.write(`[error] ${err.code === 'usage' ? 'usage ' : ''}ledger: ${err.message}\n`);
       return err.code === 'usage' ? 2 : 1;
     }
@@ -285,6 +303,19 @@ async function runAdd({ projectRoot, name, flags, stdout, stderr }) {
   const body = await loadLedger({ projectRoot, name });
   const now = new Date().toISOString();
 
+  // Ruling R1 2026-10-05: parse --id up front; a non-integer or negative
+  // value is a usage error BEFORE loading / scanning the ledger.
+  /** @type {number | undefined} */
+  let idOverride;
+  if (flags.id !== undefined) {
+    const parsed = Number(flags.id);
+    if (!Number.isInteger(parsed) || parsed < 1) {
+      stderr.write(`[error] usage ledger: --id must be a positive integer, got '${flags.id}'\n`);
+      return 2;
+    }
+    idOverride = parsed;
+  }
+
   if (name === 'brief') {
     const kind = /** @type {string} */ (flags.kind ?? 'capability');
     if (!BRIEF_KINDS.includes(/** @type {any} */ (kind))) {
@@ -299,6 +330,12 @@ async function runAdd({ projectRoot, name, flags, stdout, stderr }) {
       stderr.write('[error] usage ledger: brief add requires --text <text> or --from <path>\n');
       return 2;
     }
+    if (idOverride !== undefined && flags.from) {
+      // R1 identity is per entry; --from mints N entries, so --id has no
+      // single target. Refuse the combination to keep the harness honest.
+      stderr.write('[error] usage ledger: brief add --id applies to --text only (--from mints one entry per line and has no single id)\n');
+      return 2;
+    }
     if (flags['no-scan'] && flags.findings) {
       stderr.write('[error] usage ledger: brief add --no-scan and --findings cannot be combined\n');
       return 2;
@@ -336,10 +373,32 @@ async function runAdd({ projectRoot, name, flags, stdout, stderr }) {
     // Compute what WOULD be minted (for both the real path and dry-run).
     let cur = body;
     const added = [];
+    /** @type {'added' | 'unchanged'} */
+    let primaryStatus = 'added';
     for (const d of drafts) {
-      const step = addEntry({ name: 'brief', body: cur, entry: d, now });
+      // Only the single --text path reaches here with an idOverride (we
+      // refused --id with --from above); a per-call idOverride is passed
+      // on the first and only draft.
+      const step = addEntry({
+        name: 'brief', body: cur, entry: d, now,
+        ...(idOverride !== undefined ? { id: idOverride } : {}),
+      });
       cur = step.body;
       added.push(step.entry);
+      if (step.status === 'unchanged') primaryStatus = 'unchanged';
+    }
+
+    // Ruling R1 2026-10-05 short-circuit: when --id landed on an entry
+    // that already carried identical content, exit 0 with the unchanged
+    // signal before any scan / finding work. A replayed turn is a no-op.
+    if (primaryStatus === 'unchanged' && added.length === 1) {
+      const existing = added[0];
+      if (flags.json) {
+        stdout.write(`${JSON.stringify({ status: 'unchanged', id: existing.id, entry: existing }, null, 2)}\n`);
+      } else {
+        stdout.write(`brief-ledger: unchanged ${existing.id}\n`);
+      }
+      return 0;
     }
 
     // Convert operator-supplied --findings into openQuestion statements.
@@ -428,7 +487,18 @@ async function runAdd({ projectRoot, name, flags, stdout, stderr }) {
       default: flags.default ? String(flags.default) : null,
     };
     if (flags.blocks) entry.blocks = String(flags.blocks);
-    const step = addEntry({ name: 'decisions', body, entry, now });
+    const step = addEntry({
+      name: 'decisions', body, entry, now,
+      ...(idOverride !== undefined ? { id: idOverride } : {}),
+    });
+    if (step.status === 'unchanged') {
+      if (flags.json) {
+        stdout.write(`${JSON.stringify({ status: 'unchanged', id: step.entry.id, entry: step.entry }, null, 2)}\n`);
+      } else {
+        stdout.write(`decisions-ledger: unchanged ${step.entry.id}\n`);
+      }
+      return 0;
+    }
     await saveLedger({ projectRoot, name: 'decisions', body: step.body });
     stdout.write(`decisions-ledger: added decision ${step.entry.id}\n`);
     return 0;
@@ -449,7 +519,18 @@ async function runAdd({ projectRoot, name, flags, stdout, stderr }) {
       disposition: String(flags.disposition),
     };
     if (flags.reason) entry.reason = String(flags.reason);
-    const step = addEntry({ name: 'concerns', body, entry, now });
+    const step = addEntry({
+      name: 'concerns', body, entry, now,
+      ...(idOverride !== undefined ? { id: idOverride } : {}),
+    });
+    if (step.status === 'unchanged') {
+      if (flags.json) {
+        stdout.write(`${JSON.stringify({ status: 'unchanged', id: step.entry.id, entry: step.entry }, null, 2)}\n`);
+      } else {
+        stdout.write(`concern-ledger: unchanged ${step.entry.id}\n`);
+      }
+      return 0;
+    }
     await saveLedger({ projectRoot, name: 'concerns', body: step.body });
     stdout.write(`concern-ledger: added concern ${step.entry.id}\n`);
     return 0;
@@ -465,7 +546,18 @@ async function runAdd({ projectRoot, name, flags, stdout, stderr }) {
     finding: String(flags.finding),
     severity: flags.severity ? String(flags.severity) : 'medium',
   };
-  const step = addEntry({ name: 'probes', body, entry, now });
+  const step = addEntry({
+    name: 'probes', body, entry, now,
+    ...(idOverride !== undefined ? { id: idOverride } : {}),
+  });
+  if (step.status === 'unchanged') {
+    if (flags.json) {
+      stdout.write(`${JSON.stringify({ status: 'unchanged', id: step.entry.id, entry: step.entry }, null, 2)}\n`);
+    } else {
+      stdout.write(`probe-ledger: unchanged ${step.entry.id}\n`);
+    }
+    return 0;
+  }
   await saveLedger({ projectRoot, name: 'probes', body: step.body });
   stdout.write(`probe-ledger: added probe ${step.entry.id}\n`);
   return 0;

package/src/cli/readiness.js

@@ -16,7 +16,7 @@
 // every other query verb has.
 
 import { parseArgs } from 'node:util';
-import { readFile, stat } from 'node:fs/promises';
+import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 
 import { resolveTestPointers, walkTree } from '#core/store';
@@ -30,9 +30,9 @@ import {
   STAGE_ORDER,
   STAGE_SHORT_NAMES,
   ackable,
-  extractInterfacePathTokens,
   stagePolicy,
 } from '../query/gates.js';
+import { resolveInterfacePaths } from '../define/interface-paths.js';
 import {
   computeReadiness,
   countLitmusReadersAtHash,
@@ -129,42 +129,6 @@ const STATE_LABEL = {
   notApplicable: 'notApplicable',
 };
 
-/**
- * ADR-4131 (0.30.0 PR 5): walk the tree's TAC interfaces, extract the
- * `path:` tokens the engineer named, resolve each one against
- * `projectRoot` on disk, and return the set of tokens that resolve.
- * `shapes:pathsResolve` reads the set from the stage context and
- * decides the D3 bite without I/O. The compute is pure; this helper is
- * the one place I/O happens for the check.
- *
- * @param {string} projectRoot
- * @param {import('#core/store/walker.js').TreeModel} tree
- * @returns {Promise<Set<string>>}
- */
-async function resolveInterfacePaths(projectRoot, tree) {
-  const resolved = new Set();
-  /** @type {Set<string>} */
-  const candidates = new Set();
-  for (const tac of tree.tacs ?? []) {
-    for (const iface of tac.interfaces ?? []) {
-      const desc = typeof iface?.description === 'string' ? iface.description : '';
-      for (const token of extractInterfacePathTokens(desc)) {
-        candidates.add(token);
-      }
-    }
-  }
-  await Promise.all([...candidates].map(async (token) => {
-    try {
-      await stat(join(projectRoot, token));
-      resolved.add(token);
-    } catch {
-      // Missing path stays out of the set; the gate decides whether
-      // `authoredAt: D3` lets it through.
-    }
-  }));
-  return resolved;
-}
-
 /**
  * Read `rcf/.identity/profile.md` when it exists; return null on
  * ENOENT. Any other read error surfaces as null so the profile
@@ -390,7 +354,7 @@ function renderText(stdout, stderr, result, wallMs, checkStage, level, persona,
 
   for (const stage of result.stages) {
     if (checkStage && checkStage !== 'all' && stage.stage !== checkStage) continue;
-    stdout.write(`\n${stage.stage} (${stage.gate}): ${STATE_LABEL[stage.state] ?? stage.state}${stage.reason ? ` (${stage.reason})` : ''}\n`);
+    stdout.write(`\n${formatStageLine(stage)}\n`);
     for (const c of stage.checks) {
       if (persona && c.persona !== persona) continue;
       const mark = c.ok ? 'ok' : 'FAIL';
@@ -405,6 +369,20 @@ function renderText(stdout, stderr, result, wallMs, checkStage, level, persona,
   }
 }
 
+/**
+ * Format the per-stage header line the text report prints, e.g.
+ * `D3 (define.shapes): failing`. A `reason` trailer is appended only
+ * when the envelope carries one (the `notApplicable` envelopes do; the
+ * ADR-4138 tree-wide failing envelope does not). Exported so the
+ * printed line is testable without driving the whole CLI.
+ *
+ * @param {{ stage: string, gate: string, state: string, reason?: string }} stage
+ * @returns {string}
+ */
+export function formatStageLine(stage) {
+  return `${stage.stage} (${stage.gate}): ${STATE_LABEL[stage.state] ?? stage.state}${stage.reason ? ` (${stage.reason})` : ''}`;
+}
+
 /**
  * Render the per-persona next-action lines (spec section 4). When a
  * `--level` is given the matching persona's line heads the pair; when

package/src/core/errors/index.js

@@ -7,7 +7,7 @@
 // renders them inline in the page so an owner can see what is broken.
 
 /**
- * @typedef {('validation'|'missingFile'|'brokenReference'|'parseFailure'|'ioFailure'|'usage'|'staleCode'|'missingCodeNodes'|'duplicateId')} ErrorKind
+ * @typedef {('validation'|'missingFile'|'brokenReference'|'parseFailure'|'ioFailure'|'usage'|'staleCode'|'missingCodeNodes'|'duplicateId'|'conflict')} ErrorKind
  */
 
 /**
@@ -49,6 +49,12 @@ const VALID_KINDS = new Set([
   // with the spec-verbatim refusal message; the CLI translates it to
   // exit 3 (not exit 2) with the message printed as-is on stderr.
   'requiresAppliedCapabilities',
+  // Ruling R1 extension 2026-10-05 (DEFINE step 3, PR 292 follow-up):
+  // a same-id `rcf define create` replay whose would-be body differs
+  // from the on-disk entry refuses with `kind: 'conflict'`; the CLI
+  // translates it to exit 3 with the id and the differing field keys
+  // named in the message. Mirrors `src/define/ledgers.js` R1 add path.
+  'conflict',
 ]);
 
 /**

package/src/core/store/writer.js

@@ -52,6 +52,111 @@ function canonicalKind(kind) {
   return KIND_ALIASES[kind] ?? kind;
 }
 
+/**
+ * Fields the R1 create-replay compare ignores: every field the writer or
+ * a post-create side effect stamps on its own, never from the caller's
+ * input. A verbatim replay of a create must compare equal even after
+ * those stamps landed; every other field is deep-compared. Add a field
+ * here whenever a writer path or a post-create hook starts stamping one.
+ * Ruling R1 extension (PR 292 follow-up; list made exhaustive on the
+ * PR 293 landing review, d-2026-10-05-015 finding 2).
+ */
+export const REPLAY_IGNORE_FIELDS = Object.freeze([
+  // Writer clock: assembleBody / createCn stamp it on every create and
+  // strip any caller-supplied value (B1 fix).
+  'createdAt',
+  // Writer clock: stamped on every create and bumped by every update,
+  // including the classifier's own write-back below.
+  'updatedAt',
+  // REQ shape classifier (src/req-detection/persist.js
+  // classifyAndPersistReq): src/cli/create.js runs it after every
+  // `create req` and persists the block through updateDocument, so the
+  // first create leaves a field the replay body never carries.
+  'shapeClassification',
+]);
+const REPLAY_IGNORE_SET = new Set(REPLAY_IGNORE_FIELDS);
+
+/**
+ * Deep-equality over JSON-shaped values. Pure. Mirrors
+ * `src/define/ledgers.js` `deepEqual` so the R1 extension to `rcf
+ * define create` compares content the same way the add path does.
+ */
+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;
+}
+
+/**
+ * Compare an on-disk doc body to a would-be create body and return
+ * the sorted list of differing field keys. Ignores every field in
+ * REPLAY_IGNORE_FIELDS (writer- and classifier-owned stamps), so a
+ * verbatim replay does not show up as "updatedAt differs" or
+ * "shapeClassification differs". A key present on only one side counts as
+ * differing. R1 extension 2026-10-05 (PR 292 follow-up).
+ *
+ * @param {Record<string, unknown>} existing
+ * @param {Record<string, unknown>} candidate
+ * @returns {string[]}
+ */
+function diffDocFields(existing, candidate) {
+  /** @type {Set<string>} */
+  const differing = new Set();
+  const keys = new Set([...Object.keys(existing ?? {}), ...Object.keys(candidate ?? {})]);
+  for (const key of keys) {
+    if (REPLAY_IGNORE_SET.has(key)) continue;
+    if (!deepEqual(existing?.[key], candidate?.[key])) differing.add(key);
+  }
+  return [...differing];
+}
+
+/**
+ * Ruling R1 extension (PR 292 follow-up, amended on the PR 293 landing
+ * review): resolve a same-id create replay against the entry already on
+ * the tree. Returns null when the id is free; otherwise the
+ * `{ status: 'unchanged' }` result (identical content, nothing is
+ * written) or a `kind: 'conflict'` refusal naming the differing field
+ * keys (exit 3; never a silent overwrite). Shared by the document path
+ * (createDocument), the inline AC / TC paths and the CN path so every
+ * `rcf define create <kind> --id` follows one rule.
+ *
+ * @param {object} args
+ * @param {string} args.kind - the CLI kind, for the message
+ * @param {string} args.id
+ * @param {object | null | undefined} args.existing - the entry on the tree
+ * @param {object} args.candidate - the would-be entry
+ * @param {string} args.filePath - repo-relative file the entry lives in
+ * @param {object} [args.extra] - extra fields carried on the unchanged result
+ * @returns {object | null}
+ */
+function resolveReplay({ kind, id, existing, candidate, filePath, extra = {} }) {
+  if (!existing) return null;
+  const differing = diffDocFields(existing, candidate);
+  if (differing.length === 0) {
+    return { id, filePath, ...extra, body: existing, status: 'unchanged' };
+  }
+  return rcfError({
+    kind: 'conflict',
+    message: `create ${kind}: id ${id} already exists with different content; differing fields: ${differing.sort().join(', ')}. Use the update verb to patch.`,
+    documentId: id,
+    filePath,
+  });
+}
+
 // ---------------------------------------------------------------------------
 // B5: post-write validation gate
 // ---------------------------------------------------------------------------
@@ -496,17 +601,28 @@ export async function createDocument({ projectRoot, tree, kind, body, options =
     });
   }
 
-  // Allocate id (or take the override).
+  // Allocate id (or take the override). Ruling R1 2026-10-05 extended
+  // under w-2026-10-05-dave-013 (PR 292 follow-up): a replayed turn
+  // that carries `--id <existing>` with identical content is a no-op
+  // that returns `{ status: 'unchanged', body: existing }`; different
+  // content refuses with `kind: 'conflict'` naming the differing
+  // field keys. An unloadable (schema-invalid) doc still refuses
+  // unconditionally -- we cannot compare content against a doc we
+  // failed to load.
   let id = options.id;
+  /** @type {object | null} */
+  let existingDocForReplay = null;
   if (id) {
-    // B5: an unloadable (schema-invalid) doc still occupies its id.
-    if (tree.byId.has(id) || tree.invalidDocs?.has(id)) {
+    if (tree.invalidDocs?.has(id)) {
       return rcfError({
         kind: 'usage',
-        message: `create ${kind}: id ${id} is already taken`,
+        message: `create ${kind}: id ${id} is already taken (file on disk failed to load; repair before replaying)`,
         documentId: id,
       });
     }
+    if (tree.byId.has(id)) {
+      existingDocForReplay = tree.byId.get(id);
+    }
   } else {
     try {
       id = nextIdForKind(tree, canonical, { parentId });
@@ -528,7 +644,7 @@ export async function createDocument({ projectRoot, tree, kind, body, options =
       }
       providedOrder = maxOrder + 1;
     } else if (Number.isInteger(providedOrder)) {
-      const collision = siblings.find((sib) => sib.buildOrder === providedOrder);
+      const collision = siblings.find((sib) => sib.buildOrder === providedOrder && sib.fbsId !== id);
       if (collision) {
         return rcfError({
           kind: 'usage',
@@ -553,6 +669,16 @@ export async function createDocument({ projectRoot, tree, kind, body, options =
   });
   if (validation) return { ...validation, documentId: id };
 
+  // Ruling R1 extension 2026-10-05 (PR 292 follow-up): if the id
+  // already exists on the loaded tree, compare the would-be body to
+  // the existing doc (ignoring writer-owned timestamps) and either
+  // return `{ status: 'unchanged' }` or refuse with
+  // `kind: 'conflict'` naming the differing field keys.
+  const replay = resolveReplay({
+    kind, id, existing: existingDocForReplay, candidate: finalBody, filePath: relPath,
+  });
+  if (replay) return replay;
+
   // Cross-link ACs must resolve to existing ACs for fbs / ts.
   if (canonical === 'fbs' || canonical === 'testSuite') {
     const allAcIds = collectAllAcIds(tree);
@@ -644,10 +770,22 @@ async function createCn({ projectRoot, tree, options, body, walkErrors = [] }) {
     return rcfError({ kind: 'usage', message: 'create cn: --path is required' });
   }
 
+  // Ruling R1 extension (PR 293 landing review): a same-id replay is
+  // compared against the existing CN once the body is assembled below.
+  // An unloadable (schema-invalid) CN, or an id held by another kind,
+  // still refuses: there is no CN body to compare against.
   let id = options.id;
+  /** @type {object | null} */
+  let existingCnForReplay = null;
   if (id) {
-    if (tree.byId.has(id) || tree.invalidDocs?.has(id)) {
-      return rcfError({ kind: 'usage', message: `create cn: id ${id} is already taken`, documentId: id });
+    if (tree.invalidDocs?.has(id)) {
+      return rcfError({ kind: 'usage', message: `create cn: id ${id} is already taken (file on disk failed to load; repair before replaying)`, documentId: id });
+    }
+    if (tree.byId.has(id)) {
+      if (tree.kindById.get(id) !== 'codeNode') {
+        return rcfError({ kind: 'usage', message: `create cn: id ${id} is already taken`, documentId: id });
+      }
+      existingCnForReplay = tree.byId.get(id);
     }
   } else {
     id = nextIdForKind(tree, 'codeNode');
@@ -706,6 +844,11 @@ async function createCn({ projectRoot, tree, options, body, walkErrors = [] }) {
   const validation = validateDocument({ doc: finalBody, kind: 'codeNode', filePath: relPath });
   if (validation) return { ...validation, documentId: id };
 
+  const replay = resolveReplay({
+    kind: 'cn', id, existing: existingCnForReplay, candidate: finalBody, filePath: relPath,
+  });
+  if (replay) return replay;
+
   const absPath = pathForKindFile(projectRoot, 'codeNode', id);
   if (await fileExistsOnDisk(absPath)) {
     return rcfError({
@@ -919,12 +1062,14 @@ async function createInlineAc({ projectRoot, tree, options, body, walkErrors = [
   const seedIndex = detectSeededPhantomAcIndex(currentAcs, parentUsId);
   const replacingPhantom = seedIndex !== -1 && !options.id;
 
+  // Ruling R1 extension (PR 293 landing review): an explicit --id that
+  // already names an AC on the parent US is a replay, resolved against
+  // that AC once the would-be entry is built below.
   let acId = options.id;
+  /** @type {object | null} */
+  let existingAcForReplay = null;
   if (acId) {
-    const existing = currentAcs.some((ac) => ac.id === acId);
-    if (existing) {
-      return rcfError({ kind: 'usage', message: `create ac: id ${acId} already exists on ${parentUsId}`, documentId: acId });
-    }
+    existingAcForReplay = currentAcs.find((ac) => ac.id === acId) ?? null;
   } else if (replacingPhantom) {
     // Reuse the seed's id (AC-<us>-1) so the operator's first AC is -1.
     acId = currentAcs[seedIndex].id;
@@ -947,6 +1092,15 @@ async function createInlineAc({ projectRoot, tree, options, body, walkErrors = [
     // consumer, so we only serialise when the CLI passed a value.
     ...(body?.determinism !== undefined ? { determinism: body.determinism } : {}),
   };
+  const acReplay = resolveReplay({
+    kind: 'ac',
+    id: acId,
+    existing: existingAcForReplay,
+    candidate: acEntry,
+    filePath: `rcf/user-stories/${parentUsId.toLowerCase()}.json`,
+    extra: { parentId: parentUsId },
+  });
+  if (acReplay) return acReplay;
   const nextAcs = replacingPhantom
     ? currentAcs.map((ac, i) => (i === seedIndex ? acEntry : ac))
     : [...currentAcs, acEntry];
@@ -1073,9 +1227,14 @@ async function createInlineTc({ projectRoot, tree, options, body, walkErrors = [
     return rcfError({ kind: 'usage', message: `create tc: parent ${parentTsId} has an unrecognised id shape` });
   }
   const tcId = options.id ?? `TC-${tsSuffix}-${slug}`;
-  // Slug collision fails explicitly (§D10 OQ-P4-R-1).
   const existing = (ts.testCases ?? []).find((tc) => tc.id === tcId);
-  if (existing) {
+  // Ruling R1 extension (PR 293 landing review): idempotency is
+  // id-carried. An explicit --id that already names a TC on the parent
+  // TS is a replay, resolved against that TC once the would-be entry is
+  // built below. A derived-slug collision (no --id) still refuses
+  // explicitly (§D10 OQ-P4-R-1).
+  const replayingTc = Boolean(options.id) && Boolean(existing);
+  if (existing && !replayingTc) {
     return rcfError({
       kind: 'usage',
       message: `create tc: slug collision on ${tcId}, supply --slug explicitly`,
@@ -1089,6 +1248,15 @@ async function createInlineTc({ projectRoot, tree, options, body, walkErrors = [
     status: body?.status ?? 'pending',
     testPointer,
   };
+  const tcReplay = resolveReplay({
+    kind: 'tc',
+    id: tcId,
+    existing: replayingTc ? existing : null,
+    candidate: tcEntry,
+    filePath: `rcf/test-suites/${parentTsId.toLowerCase()}.json`,
+    extra: { parentId: parentTsId },
+  });
+  if (tcReplay) return tcReplay;
   const nextTs = {
     ...ts,
     testCases: [...(ts.testCases ?? []), tcEntry],

package/src/define/interface-paths.js

@@ -0,0 +1,47 @@
+// Shared define-time helper: resolve the `path:` tokens an engineer
+// named on TAC interfaces against the project root on disk. The pure
+// D3 `shapes:pathsResolve` check reads the resulting set from the
+// stage context; this is the one place I/O happens for the check.
+//
+// Lifted out of `src/cli/readiness.js` in issue 302 (2026-10-06) so
+// the freeze CLI can pre-resolve the same tokens and D3 agrees with
+// readiness instead of false-failing from an empty fallback set.
+// ADR-4131 (0.30.0 PR 5) still names readiness as the origin.
+
+import { stat } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { extractInterfacePathTokens } from '../query/gates.js';
+
+/**
+ * Walk the tree's TAC interfaces, extract the `path:` tokens the
+ * engineer named, resolve each one against `projectRoot` on disk, and
+ * return the set of tokens that resolve.
+ *
+ * @param {string} projectRoot
+ * @param {import('#core/store/walker.js').TreeModel} tree
+ * @returns {Promise<Set<string>>}
+ */
+export async function resolveInterfacePaths(projectRoot, tree) {
+  const resolved = new Set();
+  /** @type {Set<string>} */
+  const candidates = new Set();
+  for (const tac of tree.tacs ?? []) {
+    for (const iface of tac.interfaces ?? []) {
+      const desc = typeof iface?.description === 'string' ? iface.description : '';
+      for (const token of extractInterfacePathTokens(desc)) {
+        candidates.add(token);
+      }
+    }
+  }
+  await Promise.all([...candidates].map(async (token) => {
+    try {
+      await stat(join(projectRoot, token));
+      resolved.add(token);
+    } catch {
+      // Missing path stays out of the set; the gate decides whether
+      // `authoredAt: D3` lets it through.
+    }
+  }));
+  return resolved;
+}