rcf-lite 0.30.0 → 0.31.0

package/rcf/user-stories/us-205.json

@@ -49,6 +49,11 @@
       "id": "AC-205-8",
       "description": "[must-not] Given the LookupModal, when the user types a query, picks a result or closes the modal, then no `postMessage` is sent to the parent window, no outbound network request beyond the `./index.json` fetch is made, and no search term is written to `localStorage` / `sessionStorage` / cookies.",
       "testable": true
+    },
+    {
+      "id": "AC-205-9",
+      "description": "[happy] Given the SearchButton (`.rcf-search-btn`) in the shell's `.tools` group, when it is rendered in either theme and in each of its states (default, `:hover`, `:focus-visible`, `:active`), then the computed foreground / background contrast ratio for the button text, the icon stroke against the background and the focus-ring colour against the adjacent surface meets WCAG 2.1 AA (>= 4.5:1 for the text, >= 3:1 for the icon and the focus-ring boundary) in both the light (`:root`) and dark (`:root[data-theme=\"dark\"]`) token sets.",
+      "testable": true
     }
   ],
   "tacIds": [
@@ -60,5 +65,5 @@
     "navigation"
   ],
   "createdAt": "2026-10-02T19:00:00Z",
-  "updatedAt": "2026-10-02T19:00:00Z"
+  "updatedAt": "2026-10-04T14:00:00Z"
 }

package/rcf/user-stories/us-206.json

@@ -5,10 +5,10 @@
   "version": "0.1.0",
   "status": "draft",
   "title": "wespa's embedding contract is proved by a CI host fixture",
-  "description": "A same-origin test-host fixture served by the viewer's dev server (route `/test-host.html` behind a `--test-host` flag or an env guard; off by default so wespa's proxy allow-list is unaffected) mimics the wespa shell: a 56px header, a resizable sidebar (64px collapsed, 200-400px expanded, user-resizable live via a drag handle), a content pane carrying an `<iframe src=\"./?embed=1&theme=light\">`. The host posts `{ type: \"rcf-view-theme\", theme: \"light\"|\"dark\" }` on a toggle control; it stores no theme itself so a passing run proves the iframe reads the message. The viewer sends no outbound postMessage. Three lints run in the test suite: (1) framing lint (`GET /` returns no `X-Frame-Options`, no CSP `frame-ancestors` that forbids same-origin, and the fixture loads the iframe without a browser error); (2) target lint (no `target=\"_top\"` string in the server-rendered HTML); (3) localStorage namespace lint (every `localStorage.{setItem,getItem,removeItem}` and shared `storage.*` call site in `src/view/**` uses a key starting with `rcf-view:v1:`). See viewer UI refresh design doc section 9 and Dex's wespa requirements of 2026-10-02.",
+  "description": "A same-origin test-host fixture served by the viewer's dev server (route `/test-host.html` behind a `--test-host` flag or an env guard; off by default so wespa's proxy allow-list is unaffected) mimics the wespa shell: a 56px header, a resizable sidebar (64px collapsed, 200-400px expanded, user-resizable live via a drag handle), a content pane carrying an `<iframe src=\"./?embed=1&theme=light\">`. The host posts `{ type: \"rcf-view-theme\", theme: \"light\"|\"dark\" }` on a toggle control; it stores no theme itself so a passing run proves the iframe reads the message. The viewer sends no outbound postMessage. Three lints run in the test suite: (1) framing lint (`GET /` returns no `X-Frame-Options`, no CSP `frame-ancestors` that forbids same-origin, and the fixture loads the iframe without a browser error); (2) target lint (no `target=\"_top\"` string in the server-rendered HTML); (3) localStorage namespace lint (every `localStorage.{setItem,getItem,removeItem}` and shared `storage.*` call site in `src/view/**` uses a key starting with `rcf-view:v1:`). Amended 2026-10-04 (w-2026-10-04-dave-001): the viewer's own three-state theme control (Light|Dark|Auto) sits right of the SearchButton in non-embed mode, is hidden entirely under `embed=1` and in non-embed mode persists its setting under `rcf-view:v1:theme` per ADR-4137 (Dave's storage ruling 2026-10-04). See viewer UI refresh design doc section 9 and section 11 recommendation 6, and Dex's wespa requirements of 2026-10-02.",
   "asA": "Dex integrating the rcf-lite viewer behind wespa's reverse proxy",
-  "iWant": "a CI host fixture that proves the viewer honours the embedding contract and three lints that keep framing, target='_top' and localStorage namespace in place over time",
-  "soThat": "regressions in the embedding contract are caught in the viewer's own suite before they reach wespa",
+  "iWant": "a CI host fixture that proves the viewer honours the embedding contract and three lints that keep framing, target='_top' and localStorage namespace in place over time; and a visible three-state theme control in the standalone viewer that is hidden under embed=1",
+  "soThat": "regressions in the embedding contract are caught in the viewer's own suite before they reach wespa, and standalone viewer users can switch theme without a URL edit",
   "acceptanceCriteria": [
     {
       "id": "AC-206-1",
@@ -39,6 +39,26 @@
       "id": "AC-206-6",
       "description": "[must-not] Given the test-host fixture and the viewer page, when either is loaded, then neither posts any outbound message beyond the host's `rcf-view-theme`; the viewer sends no `postMessage` of any shape, and the test-host adds no new postMessage shape.",
       "testable": true
+    },
+    {
+      "id": "AC-206-7",
+      "description": "[happy] Given the standalone viewer loaded without `embed=1`, when the shell paints, then a three-state theme control (`role=\"group\"`, three buttons Light|Dark|Auto with `aria-pressed`) renders in the header's `.tools` group right of the SearchButton; when a button is pressed, `<html data-theme>` is set to `light` or `dark` (or the attribute is removed for Auto so the `prefers-color-scheme` media query decides) live without a reload, and the pressed button's `aria-pressed` becomes `true` while the others become `false`.",
+      "testable": true
+    },
+    {
+      "id": "AC-206-8",
+      "description": "[happy] Given the standalone (non-embed) viewer, when a theme button is pressed, then the chosen value (`light`, `dark` or `auto`) is written to `localStorage['rcf-view:v1:theme']`; on the next page load the stored value is reapplied; the boot precedence is `?theme=` wins first, then the stored value, then the default (`auto`); and the postMessage `rcf-view-theme` listener still applies live but writes nothing to the stored key.",
+      "testable": true
+    },
+    {
+      "id": "AC-206-9",
+      "description": "[must-not] Given the viewer loaded with `?embed=1`, when the shell paints, then the three-state theme control is absent from the DOM entirely (no `[data-rcf-theme-control]` element rendered, not merely hidden by CSS), and no read or write of `localStorage['rcf-view:v1:theme']` happens on load, on a postMessage theme change, or on any user action inside the viewer.",
+      "testable": true
+    },
+    {
+      "id": "AC-206-10",
+      "description": "[happy] Given the standalone viewer with a stored value `rcf-view:v1:theme = dark`, when the URL carries `?theme=light`, then on load `<html data-theme>` is `light` (the explicit query wins) and the Light button is pressed; the stored value is left as `dark` and is reused on the next load without a `?theme=` query.",
+      "testable": true
     }
   ],
   "tacIds": [
@@ -47,8 +67,9 @@
   "tags": [
     "view",
     "embedding",
+    "theme",
     "lint"
   ],
   "createdAt": "2026-10-02T20:00:00Z",
-  "updatedAt": "2026-10-02T20:00:00Z"
+  "updatedAt": "2026-10-04T14:00:00Z"
 }

package/rcf/user-stories/us-207.json

@@ -0,0 +1,36 @@
+{
+  "usId": "US-207",
+  "prdId": "PRD-001",
+  "reqId": "REQ-002",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "Every viewer text and control colour pair meets WCAG 2.1 AA in both themes",
+  "description": "A static CSS-contrast audit test parses `packages/rcf-lite/src/view/style.css`, resolves the `--sv-*` custom properties for the light (`:root`) and dark (`:root[data-theme=\"dark\"]`) token blocks, and enumerates every rule that sets `color` together with a reachable `background` / `background-color` (own rule, then the nearest ancestor surface token, default `--sv-canvas` page background). Each pair is enumerated in both themes and across every reachable state variant: default, `:hover`, `:focus`, `:focus-visible`, `:active`, `[aria-pressed=\"true\"]`, `[aria-selected=\"true\"]`, `.is-active`, `:disabled`. For each pair the WCAG relative-luminance contrast ratio is computed and asserted against the WCAG 2.1 AA thresholds (>= 4.5:1 for normal text, >= 3:1 for large text and non-text UI boundaries per WCAG 1.4.3 and 1.4.11). Pairs that cannot be resolved statically (gradients, rgba over an unknown background) are computed against the two most likely surfaces (`--sv-canvas` and the ancestor surface token) and recorded as approximate rather than skipped. The test emits a BEFORE/AFTER table under `./output/contrast-report.md` and refuses the suite on any failing pair. Scope covers the whole viewer shell, every tab, components, SearchButton and LookupModal, Readiness, Requirements, Architecture, Build (Specs and DAG), ID lookup; Mermaid and Product Map themed palettes are audited on a best-effort basis and anything bound to a third-party default is listed as a known gap with its ratio. See viewer UI refresh design doc section 9 (theme) and Baz's 2026-10-04 review (`w-2026-10-04-dave-001`).",
+  "asA": "an engineer or reviewer looking at the review surface in either theme",
+  "iWant": "every text and control colour pair in the viewer to meet WCAG 2.1 AA in both themes, pinned by a test that fails the suite when a new rule breaks the floor",
+  "soThat": "the review surface stays readable in both themes and nobody has to re-do the audit by hand on every CSS change",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-207-1",
+      "description": "[happy] Given the viewer stylesheet `src/view/style.css` and the two token blocks (`:root` and `:root[data-theme=\"dark\"]`), when the contrast test runs, then it enumerates every CSS rule that sets `color` (and every state rule merged over its base selector, so a state that changes only the background is paired with the inherited colour) paired with every reachable background (own rule, nearest ancestor surface token, page background `--sv-canvas`) and every state variant (default, `:hover`, `:focus`, `:focus-visible`, `:active`, `[aria-pressed=\"true\"]`, `[aria-selected=\"true\"]`, `.is-active`, `:disabled`), computes the WCAG relative-luminance contrast ratio for each, and asserts >= 4.5:1 for text, >= 3:1 for large text (>= 18.66px bold or >= 24px) and for non-text UI boundaries (control borders and outlines, focus rings against the adjacent colour, each enumerated as its own pair) per WCAG 1.4.3 and 1.4.11 in both the light and dark token sets.",
+      "testable": true
+    },
+    {
+      "id": "AC-207-2",
+      "description": "[failure] Given a contrast pair that falls below the applicable threshold, when the test runs, then the failure message names the selector, state, theme, foreground colour, background colour, computed ratio and the threshold applied, and the test exits non-zero so the suite blocks a merge that drops a pair below AA.",
+      "testable": true
+    }
+  ],
+  "tacIds": [
+    "TAC-4134-wespa-host-fixture"
+  ],
+  "tags": [
+    "view",
+    "contrast",
+    "accessibility",
+    "a11y",
+    "theme"
+  ],
+  "createdAt": "2026-10-04T14:00:00Z",
+  "updatedAt": "2026-10-05T12:30:00Z"
+}

package/releases/releases.yaml

@@ -40,8 +40,18 @@
 # `npm install rcf-lite`.
 
 feedVersion: 1
-latest: "0.30.0"
+latest: "0.31.0"
 releases:
+  - version: "0.31.0"
+    date: "2026-10-05"
+    breaking: true
+    headlines:
+      - "rcf-lite 0.31.0 gives the viewer a Light, Dark and Auto theme control in standalone mode and brings its text and control colours up to WCAG AA contrast in both themes, with a test that blocks any regression. Under embed=1 the control is absent, nothing is stored and the rcf-view-theme message contract is unchanged."
+      - "DEFINE step 3 rulings R1 to R13 land: tree-wide readiness checks now run before any scope short-circuit, so a narrowed scope still reports a draft marker, an unjoined core entity, an uncited standards pack, a missing Deploy ADR or an empty security or operational section anywhere in the tree. A stage whose scope is empty but whose tree-wide check fails now reads failing rather than not applicable, and the draft-settled check is tree-wide."
+      - "Write-backs that carry an id are idempotent: rcf define create <kind> --id and rcf define ledger <name> add --id exit 0 and write nothing when the same id is replayed with the same content, and exit 3 naming the differing fields when the content differs."
+    minAgentAction: null
+    notesUrl: "https://stravica.ai/docs/rcf/changelog/"
+
   - version: "0.30.0"
     date: "2026-10-03"
     breaking: true

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/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

@@ -390,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';
@@ -405,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

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',
 ]);
 
 /**