rcf-lite 0.29.0 → 0.31.0

package/src/cli/readiness.js

@@ -16,7 +16,7 @@
 // every other query verb has.
 
 import { parseArgs } from 'node:util';
-import { readFile } from 'node:fs/promises';
+import { readFile, stat } from 'node:fs/promises';
 import { join } from 'node:path';
 
 import { resolveTestPointers, walkTree } from '#core/store';
@@ -29,13 +29,17 @@ import {
   STAGE_GATES,
   STAGE_ORDER,
   STAGE_SHORT_NAMES,
+  ackable,
+  extractInterfacePathTokens,
   stagePolicy,
 } from '../query/gates.js';
 import {
   computeReadiness,
+  countLitmusReadersAtHash,
   formatTreeLine,
   formatVerdictLines,
   parseLevelFlag,
+  parseLitmusFlag,
   parsePersonaFlag,
 } from '../query/readiness.js';
 import { runWithAdmissibilityGate } from '../query/index.js';
@@ -45,6 +49,7 @@ const OPTION_SPEC = {
   check: { type: 'string' },
   level: { type: 'string' },
   persona: { type: 'string' },
+  litmus: { type: 'string' },
   help: { type: 'boolean' },
 };
 
@@ -73,11 +78,16 @@ Options:
                             brief | skeleton | shapes | stories |
                             crosscut | consistency | decisions |
                             freeze. Exits 4 on a blocking-stage
-                            failure (D1 / D2 / D4 / D7 / D8); exits 0
-                            with a visible '[warn]' line on an
-                            unacknowledged warn-with-ack failure
-                            (D3 / D5 / D6). Use --check all to print
-                            every stage under this exit-code policy.
+                            failure (D1 / D2 / D4 / D7 / D8) and on
+                            an unacknowledged D3 or D5 bite failure
+                            (ADR-4131, 0.30.0 PR 5 and PR 6); exits 0
+                            when D3 or D5 is acknowledged at the
+                            current tree hash; exits 0 with a visible
+                            '[warn]' line on an unacknowledged warn-
+                            with-ack failure (D6 until PR 7 bites it).
+                            Use
+                            --check all to print every stage under
+                            this exit-code policy.
   --level <intent|build>    Pick which verdict the exit code follows.
                             --level intent exits 4 when
                             levels.intentComplete.ok is false
@@ -97,6 +107,17 @@ Options:
                             per-stage detail to matching-persona
                             checks. Never affects the exit code or
                             the JSON content.
+  --litmus <n>              Require n distinct litmus readings at the
+                            current tree hash before passing (0.30.0
+                            PR 7, ADR-4131 extended). A litmus reading
+                            is a probe-ledger entry whose finding
+                            begins litmus:<reader>: and whose text
+                            includes the current tree hash. Fewer
+                            than n distinct readers exits 4 naming
+                            the shortfall. No process is spawned and
+                            no network call is made; the harness
+                            lands the readings through
+                            rcf define ledger probes add.
   --help                    Print this help.
 `;
 
@@ -108,6 +129,42 @@ 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
@@ -209,6 +266,15 @@ export async function main(argv, deps = {}) {
     return 2;
   }
 
+  /** @type {number | null} */
+  let litmus;
+  try {
+    litmus = parseLitmusFlag(flags.litmus);
+  } catch (err) {
+    stderr.write(`[error] usage readiness: ${/** @type {Error} */ (err).message}\n`);
+    return 2;
+  }
+
   const projectRoot = await findProjectRoot(cwd);
   if (!projectRoot) {
     stderr.write('[error] usage no project root found (no rcf/manifest.json in this directory or any ancestor). Run `npx rcf init` to create and wire a project.\n');
@@ -219,11 +285,12 @@ export async function main(argv, deps = {}) {
   const staleErrors = await checkCodeNodeResolution({ projectRoot, tree });
   const validateErrors = [...errors, ...staleErrors];
 
-  const [freeze, ledgers, testPointers, profileText] = await Promise.all([
+  const [freeze, ledgers, testPointers, profileText, resolvedPaths] = await Promise.all([
     loadFreezeRecord({ projectRoot }),
     loadAllLedgers({ projectRoot }),
     resolveTestPointers({ projectRoot, tree }),
     readProfileText(projectRoot),
+    resolveInterfacePaths(projectRoot, tree),
   ]);
 
   const startedAt = Date.now();
@@ -232,33 +299,34 @@ export async function main(argv, deps = {}) {
     : null;
 
   // Readiness is a diagnostic: even a chain that refuses admissibility
-  // wants to know which stage gate blocks it. The wrap runs first so
-  // the ruleset toolScope guard is honoured (NV-BL-SR-03 addendum);
-  // on refuse the refusal envelope is threaded through as informational
-  // context and the compute still runs (ADR-4123).
+  // wants to know which stage gate blocks it (AC-17902-4). Compute
+  // readiness once up front, then run the admissibility wrap passing
+  // the computed stages and validate-errors so it can cite
+  // NV-DL-ADM-02 (D4 floor), NV-DL-ADM-03 (D3 bite) and NV-DL-ADM-04
+  // (validate findings) alongside the NV-BL rules (PR 9).
+  /** @type {import('../query/readiness.js').ReadinessResult} */
+  const result = computeReadiness(tree, {
+    freeze,
+    ledgers,
+    profile: undefined,
+    profileText,
+    testPointers,
+    validateErrors,
+    resolvedPaths,
+  });
   const gated = await runWithAdmissibilityGate({
     tree,
     chainRulesetVersion,
-    produce: () => computeReadiness(tree, {
-      freeze,
-      ledgers,
-      profile: undefined,
-      profileText,
-      testPointers,
-      validateErrors,
-    }),
+    defineStages: result.stages,
+    defineValidateErrors: validateErrors,
+    produce: () => result,
   });
-
-  /** @type {import('../query/readiness.js').ReadinessResult} */
-  const result = gated.status === 'refused-admissibility'
-    ? computeReadiness(tree, {
-      freeze, ledgers, profile: undefined, profileText, testPointers, validateErrors,
-    })
-    : gated.payload;
   const wallMs = Date.now() - startedAt;
 
   if (gated.status === 'refused-admissibility') {
     stderr.write(`[warn] readiness: chain admissibility refused (informational; the readiness compute still ran). ${gated.refusal}\n`);
+  } else if (Array.isArray(gated.defineRules) && gated.defineRules.length > 0) {
+    stderr.write(`[warn] readiness: DEFINE-stage admissibility rules bite (informational; the readiness compute still ran): [${gated.defineRules.join(', ')}]. Resolve the failing stages or record an --ack reason on freeze.gates to satisfy recordedInChain.\n`);
   }
 
   if (flags.json) {
@@ -267,13 +335,13 @@ export async function main(argv, deps = {}) {
     // `_meta.level` is null when the flag was absent (spec section
     // 3.3): consumers can tell "no --level given" from "--level
     // build" explicitly, which matters for the ticket artefact.
-    const envelope = { ...result, _meta: { wallMs, level } };
+    const envelope = { ...result, _meta: { wallMs, level, litmus } };
     stdout.write(`${JSON.stringify(envelope, null, 2)}\n`);
-    return decideExitCode(result, checkStage, level, stderr);
+    return decideExitCode(result, checkStage, level, litmus, ledgers, stderr);
   }
 
   renderText(stdout, stderr, result, wallMs, checkStage, level, persona, profileText);
-  return decideExitCode(result, checkStage, level, stderr);
+  return decideExitCode(result, checkStage, level, litmus, ledgers, stderr);
 }
 
 /**
@@ -322,7 +390,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';
@@ -337,6 +405,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
@@ -426,13 +508,15 @@ function formatChipLine(result) {
 
 /**
  * Decide the exit code for an invocation (spec section 3.2 matrix):
- *   - No `--check` and no `--level`: always 0.
+ *   - No `--check`, no `--level`, no `--litmus`: always 0.
  *   - `--check` alone: today's stage policy (4 on blocking failure,
  *     0 with `[warn]` on warn-with-ack failure).
  *   - `--level intent`: 4 iff `levels.intentComplete.ok === false`.
  *   - `--level build`: 4 iff `levels.readyToBuild.ok === false`
  *     (stricter than `--check all`; the warn line still prints).
- *   - Both: 4 if either policy says 4.
+ *   - `--litmus <n>`: 4 iff fewer than n distinct litmus readings at
+ *     the current tree hash (spec section 11.6, ADR-4131 extended).
+ *   - Several: 4 if any policy says 4.
  *
  * Warn lines are emitted whenever a warn-with-ack stage is failing,
  * independent of exit code, so an operator always sees why.
@@ -440,13 +524,27 @@ function formatChipLine(result) {
  * @param {import('../query/readiness.js').ReadinessResult} result
  * @param {string | null} checkStage
  * @param {'intent' | 'build' | null} level
+ * @param {number | null} litmus
+ * @param {object} ledgers
  * @param {NodeJS.WritableStream} stderr
  * @returns {number}
  */
-function decideExitCode(result, checkStage, level, stderr) {
+function decideExitCode(result, checkStage, level, litmus, ledgers, stderr) {
   let exitCode = 0;
 
-  // --check policy (unchanged from PR A).
+  // --check policy. ADR-4131 (0.30.0 PR 5): D3 bites, so a failing D3
+  // without an acknowledgement at the current tree hash exits 4.
+  // 0.30.0 PR 6 lifts the bite to D5 (crosscut:catalogue, the four new
+  // D4/D2 engineer checks ride D5's ack because the --ack channel is
+  // per gate). 0.30.0 PR 7 lifts the bite to D6 (the four consistency
+  // scans; the --ack channel D3/D5/D6 already share stays unchanged).
+  // The 'acknowledged' state is already folded by foldState() in
+  // gates.js when the freeze record acknowledges the gate at the
+  // current hash, so a failing-but-unacked bite stays failing here and
+  // exit 4 is the right answer. `ackable(stage)` names the three gates
+  // that accept an --ack override; a failing ackable stage that is not
+  // acknowledged bites.
+  const BITING_STAGES = new Set(['D3', 'D5', 'D6']);
   if (checkStage) {
     const stages = checkStage === 'all'
       ? result.stages
@@ -454,9 +552,10 @@ function decideExitCode(result, checkStage, level, stderr) {
     for (const s of stages) {
       if (s.state !== 'failing') continue;
       const policy = stagePolicy(s.stage);
-      if (policy === 'blocking') {
+      const bites = BITING_STAGES.has(s.stage);
+      if (policy === 'blocking' || bites) {
         exitCode = 4;
-      } else {
+      } else if (ackable(s.stage)) {
         stderr.write(`[warn] readiness: ${s.stage} (${s.gate}) is failing without an acknowledgement at the current tree hash. Run \`rcf define freeze --ack ${s.gate} --reason "<text>"\` to acknowledge, or edit the tree to clear the failure.\n`);
       }
     }
@@ -490,6 +589,22 @@ function decideExitCode(result, checkStage, level, stderr) {
     }
   }
 
+  // --litmus policy (0.30.0 PR 7, ADR-4131 extended; R9 clarified
+  // 2026-10-03, w-2026-10-03-dave-011). Count distinct readers who
+  // have landed a probe-ledger entry at the current LITMUS HASH whose
+  // finding begins litmus:<reader>:; exit 4 when fewer than n have
+  // attested. The litmus hash is the tree hash computed with the
+  // probes ledger excluded (see computeLitmusHash in src/query/readiness.js)
+  // so a reader's own write does not shift the hash it is attesting to.
+  if (typeof litmus === 'number' && litmus > 0) {
+    const hash = result.tree.litmusHash;
+    const readers = countLitmusReadersAtHash(ledgers, hash);
+    if (readers.size < litmus) {
+      stderr.write(`[warn] readiness: --litmus ${litmus} requires ${litmus} distinct litmus reading(s) at litmus hash ${hash}; found ${readers.size}. Spawn ${litmus - readers.size} more fresh-context reader(s) and land their readings through \`rcf define ledger probes add --req <reqId> --finding "litmus:<reader>: ..." --severity low\` with the litmus hash in the finding text (read it from \`rcf define readiness --json\` under \`tree.litmusHash\`).\n`);
+      exitCode = 4;
+    }
+  }
+
   return exitCode;
 }
 

package/src/cli/validate.js

@@ -8,6 +8,8 @@ import { formatErrors } from '#core/errors';
 import { checkCodeNodeResolution, walkTree } from '#core/store';
 import { validateCompanionPinsResolvable } from '../blueprint/companions.js';
 import { findProjectRoot } from '../view/index.js';
+// 0.30.0 PR 8 (REQ-178 / TAC-4126): define-validate findings.
+import { collectDefineValidateFindings } from '../define/validate-findings.js';
 
 const OPTION_SPEC = {
   quiet: { type: 'boolean' },
@@ -133,6 +135,12 @@ export async function main(argv, deps = {}) {
   // a pin that names no known provider is exit 3.
   const companionsErrors = await validateCompanionPinsResolvable({ projectRoot, tree });
   errors.push(...companionsErrors);
+  // 0.30.0 PR 8 (REQ-178, TAC-4126): interface kind outside vocabulary,
+  // bracketed AC class prefix outside the known classes, tacIds naming
+  // a non-TAC, and an unresolving ownerRef or deliveredBy. Absence of
+  // a class marker is NOT a finding (decision 10 kept).
+  const defineValidateFindings = collectDefineValidateFindings(tree);
+  errors.push(...defineValidateFindings);
   if (flags.json) {
     const issues = errors.map((e) => ({
       id: e.documentId ?? null,

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],