rcf-lite 0.19.0 → 0.21.0

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/errors/index.js

@@ -42,6 +42,13 @@ const VALID_KINDS = new Set([
   // individually schema-clean) and from `brokenReference` (nothing
   // dangles; the graph is over-connected, not under-connected).
   'duplicateId',
+  // Visual round T-5 (spec section 5.5.1): a consumer blueprint whose
+  // requiresAppliedCapabilities gate refuses because no applied
+  // blueprint declares any of the required capabilities AND the CLI
+  // did not pass the allow-skip flag. The apply verb returns this kind
+  // 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',
 ]);
 
 /**

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