rcf-lite 0.19.0 → 0.20.0

package/src/cli/eval-coverage.js

@@ -0,0 +1,221 @@
+// `rcf audit eval coverage` subcommand handler. Sibling of `rcf audit
+// coverage`; grades non-deterministic AC coverage by EVAL docs rather
+// than TS/TC coverage. See spec section 4 of
+// projects/rcf-lite-wsd/specs/rcf-eval-node-spec-2026-09-04.md.
+//
+// Coverage rule (spec 2.3): an AC counts as covered by EVAL only when
+// at least one EVAL document lists its id in acIds[], is not
+// superseded, and has a non-pending runRecord[] entry (a "resolving"
+// EVAL, mirroring the resolving-TC rule on `rcf audit coverage`).
+//
+// Exit codes: 0 clean, 2 usage refusal, 3 tree drift, 4 strict-gate
+// refusal (any nonDeterministic AC without a resolving EVAL).
+//
+// Deterministic ACs never trigger the strict gate. A subtree with zero
+// nonDeterministic ACs passes trivially. Presence of a resolving EVAL
+// on a deterministic AC is reported as `covered-optional`, never as a
+// defect.
+
+import { parseArgs } from 'node:util';
+
+import { formatErrors } from '#core/errors';
+import { walkTree } from '#core/store';
+import { findProjectRoot } from '../view/index.js';
+import {
+  classifyCoverageScope,
+} from '../query/index.js';
+import { computeEvalCoverage } from '../query/eval-coverage.js';
+
+const OPTION_SPEC = {
+  strict: { type: 'boolean' },
+  format: { type: 'string' },
+  help: { type: 'boolean' },
+  // 0.7.0 verification-integrity precedent: opt-in extra gate on
+  // --strict that refuses any EVAL still at authoringStatus `draft`.
+  // Named --require-approved to match `rcf audit coverage`'s flag,
+  // spec section 12 Q1 recommendation.
+  'require-approved': { type: 'boolean' },
+};
+
+export const HELP = `Usage: rcf audit eval coverage [scope-id] [options]
+
+Report EVAL coverage of the non-deterministic ACs on the scoped
+subtree. An AC counts as covered by EVAL only when at least one EVAL
+document lists its id in acIds[], is not superseded, and has a
+non-pending runRecord[] entry (a "resolving" EVAL, mirroring the
+resolving-TC rule on \`rcf audit coverage\`).
+
+Deterministic ACs never trigger the strict gate. Presence of a
+resolving EVAL on a deterministic AC is reported as covered-optional,
+never as a defect.
+
+Positional:
+  scope-id                  Optional PRD / REQ / US id to scope the
+                            audit to a subtree. Below-AC ids exit 2.
+
+Options:
+  --strict                  Per-AC-strict mode; exits 4 on any
+                            nonDeterministic AC without a resolving
+                            EVAL. Deterministic ACs are never gated.
+  --require-approved        Extra --strict gate: refuse any EVAL still
+                            at authoringStatus 'draft'.
+  --format <format>         table (default) | json | mermaid
+  --help                    Print this help
+`;
+
+const VALID_FORMATS = new Set(['table', 'json', 'mermaid']);
+
+/**
+ * @param {string[]} argv - argv slice after `eval coverage`
+ * @param {object} [deps]
+ * @returns {Promise<number>}
+ */
+export async function main(argv, deps = {}) {
+  const stdout = deps.stdout ?? process.stdout;
+  const stderr = deps.stderr ?? process.stderr;
+  const cwd = deps.cwd ?? process.cwd();
+
+  let parsed;
+  try {
+    parsed = parseArgs({ args: argv, options: OPTION_SPEC, allowPositionals: true, strict: true });
+  } catch (err) {
+    stderr.write(`[error] usage ${err.message}\n`);
+    stderr.write(HELP);
+    return 2;
+  }
+  const flags = parsed.values;
+  const positionals = parsed.positionals;
+  if (flags.help) { stdout.write(HELP); return 0; }
+
+  const format = flags.format ?? 'table';
+  if (!VALID_FORMATS.has(format)) {
+    stderr.write(`[error] usage eval coverage: unknown --format ${format} (expected table | json | mermaid)\n`);
+    return 2;
+  }
+  if (positionals.length > 1) {
+    stderr.write('[error] usage eval coverage: multiple positional ids are not supported\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');
+    return 2;
+  }
+  const { tree, errors } = await walkTree({ projectRoot });
+  if (errors.length > 0) {
+    stderr.write(`${formatErrors(errors, { verbose: false, strict: false })}\n`);
+    return 3;
+  }
+
+  let scopeId = null;
+  if (positionals.length === 1) {
+    scopeId = positionals[0];
+    if (scopeId.includes('*') || scopeId.includes('?')) {
+      stderr.write('[error] usage eval coverage: wildcard / glob positional not supported\n');
+      return 2;
+    }
+    const classification = classifyCoverageScope(tree, scopeId);
+    if (classification === 'below-ac') {
+      stderr.write(
+        `[error] usage eval coverage: scope-id ${scopeId} is below the AC layer or off the REQ chain; ` +
+          'eval coverage scope must be a PRD / REQ / US id\n',
+      );
+      return 2;
+    }
+    if (classification === 'not-found' || classification === 'unknown-kind') {
+      stderr.write(`[error] usage eval coverage: id ${scopeId} not found\n`);
+      return 2;
+    }
+  }
+
+  const report = computeEvalCoverage(tree, { scopeId });
+
+  if (format === 'json') stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  else if (format === 'mermaid') stdout.write(formatMermaid(report));
+  else stdout.write(formatTable(report));
+
+  // --strict on any missing = exit 4 (CI-gate friendly). Otherwise 0.
+  if (flags.strict && !report.ok) return 4;
+
+  if (flags.strict && flags['require-approved']) {
+    const draftEvalIds = (tree.evals ?? []).filter((e) => e.status !== 'approved').map((e) => e.id);
+    if (draftEvalIds.length > 0) {
+      stderr.write(`[error] eval coverage --strict --require-approved: refused - ${draftEvalIds.length} EVAL(s) still not approved: ${draftEvalIds.join(', ')}\n`);
+      return 4;
+    }
+  }
+  return 0;
+}
+
+/**
+ * Render the EVAL coverage report as a plain-text table.
+ *
+ * @param {import('../query/eval-coverage.js').EvalCoverageReport} report
+ * @returns {string}
+ */
+export function formatTable(report) {
+  const lines = [];
+  lines.push('EVAL coverage report');
+  if (report.scopeId) lines.push(`scope: ${report.scopeId}`);
+  lines.push('');
+  if (report.nonDeterministicCount === 0) {
+    lines.push('no nonDeterministic ACs on this chain; audit passes trivially');
+    lines.push('');
+    lines.push(`ok=${report.ok}`);
+    return `${lines.join('\n')}\n`;
+  }
+  lines.push('  AC              US        determinism      evalStatus  outcome            evalId');
+  for (const ac of report.acs) {
+    const cols = [
+      pad(ac.acId, 15),
+      pad(ac.usId, 9),
+      pad(ac.determinism, 16),
+      pad(ac.evalStatus, 11),
+      pad(ac.outcome, 18),
+      ac.evalId ?? '',
+    ];
+    lines.push(`  ${cols.join(' ')}`);
+  }
+  lines.push('');
+  lines.push(
+    `nonDeterministic=${report.nonDeterministicCount}, `
+    + `covered=${report.coveredCount}, `
+    + `missing=${report.missingCount}, ok=${report.ok}`,
+  );
+  return `${lines.join('\n')}\n`;
+}
+
+/**
+ * Colour-coded mermaid summary. Spec section 4: green deterministic
+ * (out of scope), amber nonDeterministic with a resolving EVAL, red
+ * nonDeterministic without one.
+ *
+ * @param {import('../query/eval-coverage.js').EvalCoverageReport} report
+ * @returns {string}
+ */
+export function formatMermaid(report) {
+  const lines = ['graph TD'];
+  lines.push('  classDef deterministic fill:#d1f2c4,stroke:#2f7a1e;');
+  lines.push('  classDef covered fill:#ffe6a1,stroke:#a56a00;');
+  lines.push('  classDef missing fill:#f4b4b4,stroke:#a00000;');
+  for (const ac of report.acs) {
+    const cls = ac.outcome === 'missing'
+      ? 'missing'
+      : ac.outcome === 'covered'
+        ? 'covered'
+        : 'deterministic';
+    const label = ac.evalId ? `${ac.acId}\\n[${ac.evalId}]` : ac.acId;
+    lines.push(`  ${idOf(ac.acId)}["${label}"]:::${cls}`);
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+function pad(s, w) {
+  const str = String(s ?? '');
+  return str.length >= w ? str : str + ' '.repeat(w - str.length);
+}
+
+function idOf(s) {
+  return String(s).replace(/[^A-Za-z0-9]+/g, '_');
+}

package/src/cli/eval.js

@@ -0,0 +1,43 @@
+// `rcf audit eval <sub-verb>` dispatcher. v1 exposes one sub-verb:
+// `coverage`. The compound invocation `rcf audit eval coverage`
+// matches the spec text exactly (section 4). Future sibling sub-verbs
+// (`rcf audit eval trace`, `rcf build eval run`, ...) plug in here.
+
+import { main as evalCoverageMain, HELP as COVERAGE_HELP } from './eval-coverage.js';
+
+export const HELP = `Usage: rcf audit eval <sub-verb> [options]
+
+Sub-verbs:
+  coverage           Report EVAL coverage over the chain.
+
+Options:
+  --help             Print this help
+`;
+
+const SUB_VERBS = {
+  coverage: evalCoverageMain,
+};
+
+/**
+ * @param {string[]} argv - argv slice after `eval`
+ * @param {object} [deps]
+ * @returns {Promise<number>}
+ */
+export async function main(argv, deps = {}) {
+  const stdout = deps.stdout ?? process.stdout;
+  const stderr = deps.stderr ?? process.stderr;
+  if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h') {
+    stdout.write(HELP);
+    return 0;
+  }
+  const subVerb = argv[0];
+  const handler = SUB_VERBS[subVerb];
+  if (!handler) {
+    stderr.write(`[error] usage unknown sub-verb '${subVerb}' under 'audit eval'.\n`);
+    stderr.write(HELP);
+    return 2;
+  }
+  return await handler(argv.slice(1), deps);
+}
+
+export { COVERAGE_HELP };

package/src/cli/finalise.js

@@ -37,13 +37,17 @@ import { kindOf } from '../query/index.js';
 import {
   buildVerifyArgs,
   composeShipWithoutVerifiedRecord,
+  composeShipWithoutEvalRecord,
   detectVerify,
+  findEvalRefusalAcs,
   findMockOnlyDeclaredAcs,
   loadReport,
+  reportHasEvalRefusal,
   reportHasMockOnlyDeclared,
   resolveAbsentVerify,
   spawnVerify,
   summariseReport,
+  writeShipWithoutEvalRecord,
   writeShipWithoutVerifiedRecord,
 } from '../finalise/index.js';
 
@@ -74,6 +78,11 @@ const OPTION_SPEC = {
   // ship the FBS 'complete' without promoting to 'verified'. Records
   // the operator's ack on the manifest.
   'ship-without-verified': { type: 'boolean' },
+  // rcf-eval-node spec 2026-09-04 sections 5.2 + 8: sister opt-out for
+  // EVAL-MISSING / EVAL-BELOW-THRESHOLD. Takes a mandatory reason
+  // string (spec section 8: missing reason exits 2). Shape mirrors
+  // `--provision`: a value that looks like a flag is refused.
+  'ship-without-eval': { type: 'string' },
   quiet: { type: 'boolean' },
   help: { type: 'boolean' },
 };
@@ -123,6 +132,13 @@ Options:
                             'complete'. Without this flag, the gate
                             refuses to promote when any AC lands in
                             those verdicts.
+  --ship-without-eval "..."  Acknowledge EVAL-MISSING /
+                            EVAL-BELOW-THRESHOLD per-AC verdicts and
+                            proceed with an audit-log entry
+                            (rcf-eval-node spec section 5.2). Reason
+                            string is mandatory; a missing reason exits
+                            2. The ack lands on the manifest under
+                            shipWithoutEval[] with a monotonic id.
   --quiet                   Suppress non-error confirmations
   --help                    Print this help
 
@@ -345,6 +361,54 @@ export async function main(argv, deps = {}) {
       stderr.write(`Report: ${outPath}\n`);
       return 4;
     }
+    // rcf-eval-node spec section 5.2: EVAL-MISSING / EVAL-BELOW-THRESHOLD
+    // refusal, sister of the mock-only refusal above. Opt-out via
+    // --ship-without-eval "<reason>"; missing reason exits 2, matching
+    // the ship-without-verified argv-shape lesson.
+    if (passLoaded.ok && reportHasEvalRefusal(passLoaded.report)) {
+      const evalDeclared = findEvalRefusalAcs(passLoaded.report);
+      const missingAcIds = evalDeclared.filter((e) => e.verdict === 'EVAL-MISSING').map((e) => e.acId);
+      const belowAcIds = evalDeclared.filter((e) => e.verdict === 'EVAL-BELOW-THRESHOLD').map((e) => e.acId);
+      const swe = flags['ship-without-eval'];
+      if (swe !== undefined) {
+        // A --ship-without-eval that looks like a flag is a swallowed
+        // next option; refuse it (parallel to the --provision guard).
+        if (typeof swe !== 'string' || swe.startsWith('-') || swe.trim().length === 0) {
+          stderr.write('[error] usage finalise: --ship-without-eval requires a reason string\n');
+          return 2;
+        }
+        const evalAck = composeShipWithoutEvalRecord({
+          manifest: tree.manifest,
+          fbsId,
+          reason: swe,
+          declaredAcs: evalDeclared,
+          reportPath: outPath,
+        });
+        const evalAckResult = await writeShipWithoutEvalRecord({
+          projectRoot, tree, record: evalAck,
+        });
+        if (isRcfError(evalAckResult)) {
+          if (evalAckResult.kind === 'ioFailure') { writeUnexpectedFailure(evalAckResult, stderr); return 1; }
+          stderr.write(`[error] ${evalAckResult.kind} ${evalAckResult.message}\n`);
+          if (evalAckResult.kind === 'validation' || evalAckResult.kind === 'brokenReference') return 3;
+          return 1;
+        }
+        if (!quiet) {
+          stdout.write(`[finalise] gate passed and ${evalDeclared.length} AC(s) came back with EVAL refusals; --ship-without-eval acknowledged (${evalAck.id} on rcf/manifest.json, reason: ${swe}); ${fbsId} left '${currentStatus}'. Report: ${outPath}\n`);
+          stdout.write(summariseReport(passLoaded.report));
+        }
+        return 0;
+      }
+      if (missingAcIds.length > 0) {
+        stderr.write(`finalise refused: EVAL missing on AC(s) ${missingAcIds.join(', ')}; author an EVAL or --ship-without-eval "reason"\n`);
+      }
+      if (belowAcIds.length > 0) {
+        stderr.write(`finalise refused: EVAL below threshold on AC(s) ${belowAcIds.join(', ')}; investigate the run record or --ship-without-eval "reason"\n`);
+      }
+      stderr.write(summariseReport(passLoaded.report));
+      stderr.write(`Report: ${outPath}\n`);
+      return 4;
+    }
     const result = await updateDocument({
       projectRoot, tree, id: fbsId, sets: [{ path: 'executionStatus', value: 'verified' }], options: {},
     });

package/src/cli/help.js

@@ -15,6 +15,7 @@
 
 import { HELP as BUILD_HELP } from './build.js';
 import { HELP as COVERAGE_HELP } from './coverage.js';
+import { HELP as AUDIT_EVAL_HELP } from './eval.js';
 import { HELP as CREATE_HELP } from './create.js';
 import { HELP as DELETE_HELP } from './delete.js';
 import { HELP as DOCTOR_HELP } from './doctor.js';
@@ -237,6 +238,8 @@ Verbs:
   view                     Live HTML tree render (long-running server).
   coverage [scope-id]      Structural coverage over the PRD -> REQ -> US ->
                            AC -> TS -> TC chain.
+  eval coverage [scope-id] EVAL coverage over nonDeterministic ACs
+                           (spec rcf-eval-node-2026-09-04 section 4).
   trace <id>               Walk the graph forward, back, or both from a node.
   impact <id>              Change-impact fan-out from a node.
 
@@ -299,6 +302,7 @@ export const HELP_MAP = {
     coverage: COVERAGE_HELP,
     trace: TRACE_HELP,
     impact: IMPACT_HELP,
+    eval: AUDIT_EVAL_HELP,
   },
 };
 

package/src/core/store/ids.js

@@ -34,7 +34,10 @@
 // Family membership (the single source for downstream re-exports)
 // ---------------------------------------------------------------------------
 
-export const PREFIX_FAMILIES = Object.freeze(['REQ', 'US', 'PRD', 'BS', 'TAD', 'TS']);
+// EVAL joins the prefix families in rcf-schemas 0.6.0 (evalId shape mirrors
+// tsId: three-digit minimum with an optional lowercase kebab-slug prefix).
+// EVAL is a peer of a Test Suite; it grades non-deterministic behaviour.
+export const PREFIX_FAMILIES = Object.freeze(['REQ', 'US', 'PRD', 'BS', 'TAD', 'TS', 'EVAL']);
 export const SUFFIX_FAMILIES = Object.freeze(['ADR', 'TAC', 'FBS', 'CN']);
 export const UNNAMESPACED_FAMILIES = Object.freeze(['AC', 'TC']);
 
@@ -85,6 +88,7 @@ const FAMILY_TO_LOCATION = new Map([
   ['FBS', { kind: 'fbs', subdir: 'fbs', rootFile: null }],
   ['TS', { kind: 'testSuite', subdir: 'test-suites', rootFile: null }],
   ['CN', { kind: 'codeNode', subdir: 'code-nodes', rootFile: null }],
+  ['EVAL', { kind: 'evalDoc', subdir: 'evals', rootFile: null }],
   ['PRD', { kind: 'prd', subdir: null, rootFile: 'prd.json' }],
   ['TAD', { kind: 'tad', subdir: null, rootFile: 'tad.json' }],
   ['BS', { kind: 'buildSequence', subdir: null, rootFile: 'build-sequence.json' }],

package/src/core/store/init.js

@@ -231,6 +231,10 @@ export async function initProject({ projectRoot, projectName = 'New RCF Project'
     'rcf/adrs',
     'rcf/fbs',
     'rcf/test-suites',
+    // rcf-schemas 0.6.0: EVAL doc subdir. Empty by default; created so
+    // `rcf audit eval coverage` can find the subdir when the walker
+    // enumerates children even before any EVAL has been authored.
+    'rcf/evals',
   ];
   for (const d of dirs) {
     await mkdir(join(projectRoot, d), { recursive: true });

package/src/core/store/loader.js

@@ -30,6 +30,10 @@ export function subdirFor(kind) {
     case 'testSuite': return 'test-suites';
     // Phase 10 (X2 CodeNode bridge): Code Node document type.
     case 'codeNode': return 'code-nodes';
+    // rcf-schemas 0.6.0 EVAL doc type. One file per EVAL under rcf/evals/.
+    // EVAL is optional in the chain; required only for ACs marked
+    // determinism: nonDeterministic.
+    case 'evalDoc': return 'evals';
     default: return null;
   }
 }

package/src/core/store/validator.js

@@ -28,6 +28,9 @@ import testSuiteSchema from '@stravica-ai/rcf-schemas/schemas/test-suite.schema.
 // Phase 10 (X2 CodeNode bridge): 11th document kind, delivered in
 // @stravica-ai/rcf-schemas@0.3.0.
 import cnSchema from '@stravica-ai/rcf-schemas/schemas/cn.schema.json' with { type: 'json' };
+// rcf-schemas 0.6.0: the EVAL doc type. Optional peer of a Test Suite,
+// used to grade nonDeterministic acceptance criteria.
+import evalSchema from '@stravica-ai/rcf-schemas/schemas/eval.schema.json' with { type: 'json' };
 
 import { rcfError } from '../errors/index.js';
 
@@ -39,7 +42,7 @@ import { rcfError } from '../errors/index.js';
 // schema, unmodified.
 
 /**
- * @typedef {('manifest'|'prd'|'req'|'userStory'|'tad'|'tac'|'adr'|'buildSequence'|'fbs'|'testSuite'|'codeNode')} DocKind
+ * @typedef {('manifest'|'prd'|'req'|'userStory'|'tad'|'tac'|'adr'|'buildSequence'|'fbs'|'testSuite'|'codeNode'|'evalDoc')} DocKind
  */
 
 const SCHEMAS = {
@@ -55,6 +58,8 @@ const SCHEMAS = {
   testSuite: testSuiteSchema,
   // Phase 10: Code Node.
   codeNode: cnSchema,
+  // rcf-schemas 0.6.0: EVAL doc.
+  evalDoc: evalSchema,
 };
 
 const ID_FIELD = {
@@ -72,6 +77,8 @@ const ID_FIELD = {
   testSuite: 'id',
   // Phase 10: Code Node.
   codeNode: 'cnId',
+  // rcf-schemas 0.6.0: EVAL doc uses the plain `id` field (mirrors TS).
+  evalDoc: 'id',
 };
 
 let cachedAjv = null;

package/src/core/store/walker.js

@@ -87,7 +87,9 @@ function idFromFilenameStem(stem) {
 // Phase 10 (X2 CodeNode bridge): 'codeNode' appended. The load-then-invert
 // engine treats it exactly like any other child kind - extending the graph
 // into code is additive, not a rewrite (PoC-proven, poc/codenode-bridge).
-const CHILD_KINDS = ['req', 'userStory', 'tac', 'adr', 'fbs', 'testSuite', 'codeNode'];
+// rcf-schemas 0.6.0: 'evalDoc' appended. EVAL is a peer of TS; it grades
+// non-deterministic ACs and rides the same load-then-invert engine.
+const CHILD_KINDS = ['req', 'userStory', 'tac', 'adr', 'fbs', 'testSuite', 'codeNode', 'evalDoc'];
 
 const ID_FIELD_BY_KIND = {
   prd: 'prdId',
@@ -102,6 +104,8 @@ const ID_FIELD_BY_KIND = {
   testSuite: 'id',
   // Phase 10: Code Node.
   codeNode: 'cnId',
+  // rcf-schemas 0.6.0: EVAL doc.
+  evalDoc: 'id',
 };
 
 function idOfDoc(doc, kind) {
@@ -125,6 +129,9 @@ function newTree() {
     testSuites: [],
     // Phase 10 (X2 CodeNode bridge): Code Nodes.
     codeNodes: [],
+    // rcf-schemas 0.6.0: EVAL docs. A peer of testSuites; walked and
+    // integrity-checked like every other child kind.
+    evals: [],
     byId: new Map(),
     rawById: new Map(),
     kindById: new Map(),
@@ -146,6 +153,10 @@ function newTree() {
     // fbsByAcId / dependentsByFbsId for the code layer.
     cnByAcId: new Map(),
     dependentsByCnId: new Map(),
+    // rcf-schemas 0.6.0: EVAL -> AC inversion. Key: acId, value: EVAL ids
+    // whose acIds[] names that AC. Consumed by `rcf audit eval coverage`
+    // to answer "does this AC have a resolving EVAL?" in constant time.
+    evalByAcId: new Map(),
   };
 }
 
@@ -174,6 +185,8 @@ function recordDoc(tree, id, doc, raw, kind) {
     case 'testSuite': tree.testSuites.push(doc); break;
     // Phase 10: Code Node.
     case 'codeNode': tree.codeNodes.push(doc); break;
+    // rcf-schemas 0.6.0: EVAL doc.
+    case 'evalDoc': tree.evals.push(doc); break;
     default: break;
   }
 }
@@ -315,6 +328,8 @@ export async function walkTree({ projectRoot }) {
   tree.fbsItems = sortById(tree.fbsItems, 'fbsId');
   tree.testSuites = sortById(tree.testSuites, 'id');
   tree.codeNodes = sortById(tree.codeNodes, 'cnId'); // Phase 10
+  // rcf-schemas 0.6.0: EVAL doc uses `id` field (mirrors TS).
+  tree.evals = sortById(tree.evals, 'id');
 
   // Referential integrity + graph inversion.
   invertGraph(tree);
@@ -416,11 +431,21 @@ function invertGraph(tree) {
     }
   }
 
+  // rcf-schemas 0.6.0: invert EVAL edges.
+  //   EVAL.usId -> US (parent-child)
+  //   EVAL.acIds -> evalByAcId (keyed on AC, value = EVAL grading it)
+  for (const evalDoc of tree.evals) {
+    if (isKind(evalDoc.usId, 'userStory')) linkParent(evalDoc.id, evalDoc.usId);
+    for (const acId of evalDoc.acIds ?? []) {
+      if (acIds.has(acId)) pushToMap(tree.evalByAcId, acId, evalDoc.id);
+    }
+  }
+
   // Sort children lists deterministically.
   for (const [k, list] of tree.childrenByParent) {
     tree.childrenByParent.set(k, [...list].sort());
   }
-  for (const map of [tree.fbsByAcId, tree.dependentsByFbsId, tree.tsByAcId, tree.usByTacId, tree.cnByAcId, tree.dependentsByCnId]) {
+  for (const map of [tree.fbsByAcId, tree.dependentsByFbsId, tree.tsByAcId, tree.usByTacId, tree.cnByAcId, tree.dependentsByCnId, tree.evalByAcId]) {
     for (const [k, list] of map) map.set(k, [...list].sort());
   }
 }
@@ -519,6 +544,8 @@ export function simulateWriteErrors({ tree, preErrors = [], upserts = [], delete
   post.fbsItems = sortById(post.fbsItems, 'fbsId');
   post.testSuites = sortById(post.testSuites, 'id');
   post.codeNodes = sortById(post.codeNodes, 'cnId'); // Phase 10
+  // rcf-schemas 0.6.0: EVAL doc.
+  post.evals = sortById(post.evals, 'id');
   invertGraph(post);
   collectBrokenReferences(post, errors);
   // w-2026-07-28-017: uniqueness is part of the post-write gate, so a
@@ -953,4 +980,46 @@ function collectBrokenReferences(tree, errors) {
       });
     }
   }
+
+  // rcf-schemas 0.6.0: EVAL doc cross-link integrity. Mirrors the TS
+  // parent + acIds shape (usId -> parent US; every acId -> a known AC).
+  // Cross-US EVAL bindings are refused at v1: an EVAL only grades ACs
+  // that live on its parent US, matching the TS scoping rule.
+  for (const evalDoc of tree.evals) {
+    check({
+      docId: evalDoc.id,
+      docKind: 'evalDoc',
+      fromField: 'usId',
+      targetId: evalDoc.usId,
+      expectedKind: 'userStory',
+      filePath: `rcf/evals/${(evalDoc.id ?? '').toLowerCase()}.json`,
+      message: `EVAL ${evalDoc.id} references unknown US ${evalDoc.usId}`,
+    });
+    const parentUs = tree.userStories.find((u) => u.usId === evalDoc.usId);
+    const parentAcIds = new Set(
+      (parentUs?.acceptanceCriteria ?? []).map((ac) => ac?.id).filter(Boolean),
+    );
+    for (const [i, acId] of (evalDoc.acIds ?? []).entries()) {
+      if (!acIds.has(acId)) {
+        errors.push(rcfError({
+          kind: 'brokenReference',
+          message: `EVAL ${evalDoc.id} references unknown acceptance criterion ${acId}`,
+          documentId: evalDoc.id,
+          filePath: `rcf/evals/${(evalDoc.id ?? '').toLowerCase()}.json`,
+          field: `acIds[${i}]`,
+          rule: 'resolveTo:ac',
+        }));
+        tree.brokenIds.add(acId);
+      } else if (parentUs && !parentAcIds.has(acId)) {
+        errors.push(rcfError({
+          kind: 'brokenReference',
+          message: `EVAL ${evalDoc.id} lists AC ${acId} that lives outside its parent US ${evalDoc.usId} (cross-US EVAL bindings are not permitted)`,
+          documentId: evalDoc.id,
+          filePath: `rcf/evals/${(evalDoc.id ?? '').toLowerCase()}.json`,
+          field: `acIds[${i}]`,
+          rule: 'evalAcIdsScopedToParentUs',
+        }));
+      }
+    }
+  }
 }

package/src/core/store/writer.js

@@ -862,6 +862,10 @@ async function createInlineAc({ projectRoot, tree, options, body, walkErrors = [
     ...(body?.given !== undefined ? { given: body.given } : {}),
     ...(body?.when !== undefined ? { when: body.when } : {}),
     ...(body?.then !== undefined ? { then: body.then } : {}),
+    // rcf-eval-node spec 2026-09-04 section 2.2: authored determinism
+    // survives write. Absence is treated as 'deterministic' by every
+    // consumer, so we only serialise when the CLI passed a value.
+    ...(body?.determinism !== undefined ? { determinism: body.determinism } : {}),
   };
   const nextAcs = replacingPhantom
     ? currentAcs.map((ac, i) => (i === seedIndex ? acEntry : ac))