rcf-lite 0.19.0 → 0.21.0

package/src/cli/blueprint.js

@@ -184,6 +184,14 @@ const OPTION_SPEC = {
   // Companion-suggestion mechanism (core-companions spec section 2).
   companion: { type: 'string', multiple: true },
   'no-companion-suggestions': { type: 'boolean' },
+  // Capability-declaration mechanism (visual round T-5 spec 5.5.1,
+  // 5.5.2). --allow-no-auth-yet is the override for the
+  // requiresAppliedCapabilities gate. --answer <id>=<value> is
+  // repeatable; --answers <file> reads a JSON object mapping elicit
+  // ids to values. Both feed the elicitation phase in applyBlueprint.
+  'allow-no-auth-yet': { type: 'boolean' },
+  answer: { type: 'string', multiple: true },
+  answers: { type: 'string' },
 };
 
 /**
@@ -286,9 +294,54 @@ export async function main(argv, deps = {}) {
         }
       }
     }
+    // Capability-declaration mechanism (visual round T-5). Compose
+    // the operator-supplied elicit answers bag from --answers <file>
+    // (JSON object) and --answer <id>=<value> (repeatable). Later
+    // --answer entries override --answers file entries so a shell
+    // one-liner beats a stored default without editing the file.
+    let elicitAnswers = {};
+    if (typeof parsed.values.answers === 'string' && parsed.values.answers.length > 0) {
+      try {
+        const raw = await (await import('node:fs/promises')).readFile(parsed.values.answers, 'utf8');
+        const parsedBag = JSON.parse(raw);
+        if (typeof parsedBag !== 'object' || parsedBag === null || Array.isArray(parsedBag)) {
+          stderr.write(`[error] blueprint add: --answers file must contain a JSON object of id -> value.\n`);
+          return 2;
+        }
+        elicitAnswers = { ...parsedBag };
+      } catch (err) {
+        stderr.write(`[error] blueprint add: --answers file read failed: ${err.message}\n`);
+        return 2;
+      }
+    }
+    if (Array.isArray(parsed.values.answer)) {
+      for (const entry of parsed.values.answer) {
+        const eq = entry.indexOf('=');
+        if (eq < 1) {
+          stderr.write(`[error] blueprint add: --answer expects <id>=<value>; got '${entry}'.\n`);
+          return 2;
+        }
+        elicitAnswers[entry.slice(0, eq)] = entry.slice(eq + 1);
+      }
+    }
+    // Custom-auth capability elicits (visual round T-5 spec 5.5
+    // "Risks"): providesCapability elicits fire pre-refusal. On a
+    // TTY, prompt the operator for any unanswered custom-auth elicits
+    // through readline so a fresh project with no shelf auth can pass
+    // the requiresAppliedCapabilities gate by declaring what its own
+    // auth provides. Non-interactive runs skip the prompt and read
+    // answers from the bag only.
+    const stdin = deps.stdin ?? process.stdin;
+    const isTty = Boolean(stdin && stdin.isTTY);
+    const customAuthReadLine = isTty
+      ? await createCustomAuthReadLine({ stdin, stdout })
+      : null;
     const result = await applyBlueprint({
       projectRoot, tree, source,
       namespaceOverride: parsed.values.namespace,
+      allowNoAuthYet: parsed.values['allow-no-auth-yet'] === true,
+      elicitAnswers,
+      customAuthReadLine,
       // Library-qualified resolves rewire the applied identity under
       // the library prefix and forward the library's declared bands
       // for the apply-time gate (spec §5.3, §8.3). The qualified typed
@@ -321,6 +374,19 @@ export async function main(argv, deps = {}) {
       }
     }
     if (isRcfError(result)) {
+      // Capability-declaration refusal (visual round T-5 spec 5.5.1)
+      // is exit 3, and the message is spec-verbatim (built by
+      // buildRefusalMessage in blueprint/capabilities.js): print it
+      // as-is on stderr, no [error] prefix. Every other rcfError
+      // stays exit 2 with the [error] prefix.
+      if (result.kind === 'requiresAppliedCapabilities') {
+        if (parsed.values.json) {
+          stderr.write(`${JSON.stringify({ refused: true, error: { kind: result.kind, message: result.message } })}\n`);
+        } else {
+          stderr.write(`${result.message}\n`);
+        }
+        return 3;
+      }
       if (parsed.values.json) {
         stderr.write(`${JSON.stringify({ refused: true, error: { kind: result.kind, message: result.message } })}\n`);
       } else {
@@ -759,3 +825,29 @@ function parseResolveOptions(rawList, reason) {
   }
   return { value: out };
 }
+
+/**
+ * Build a readline-backed prompt function for custom-auth capability
+ * elicits (visual round T-5 spec 5.5 "Risks"). Wraps node:readline in
+ * a promise so `runCustomAuthCapabilityElicits` can `await` each line.
+ * Only used when stdin is a TTY; the callback closes the interface on
+ * first shutdown to avoid leaking file descriptors.
+ *
+ * @param {{ stdin: NodeJS.ReadableStream, stdout: NodeJS.WritableStream }} deps
+ * @returns {Promise<(prompt: string) => Promise<string>>}
+ */
+async function createCustomAuthReadLine({ stdin, stdout }) {
+  const { createInterface } = await import('node:readline');
+  const rl = createInterface({ input: stdin, output: stdout, terminal: true });
+  let closed = false;
+  return (prompt) => new Promise((resolve) => {
+    if (closed) return resolve('');
+    rl.question(prompt, (answer) => {
+      if (!closed) {
+        try { rl.close(); } catch { /* fine */ }
+        closed = true;
+      }
+      resolve(answer);
+    });
+  });
+}

package/src/cli/browser-verify.js

@@ -18,13 +18,18 @@
 
 import { parseArgs } from 'node:util';
 import process from 'node:process';
+import { isAbsolute, resolve } from 'node:path';
 
 import { walkTree } from '#core/store';
 import { writeUnexpectedFailure, rcfError } from '#core/errors';
 
 import { findProjectRoot } from '../view/index.js';
 import {
+  bootIfNeeded,
   composeOperatorSessionRecord,
+  createPackBrowser,
+  loadProbePacks,
+  pickBootFromPacks,
   runAgentScreenshotCritique,
   stubBrowserDriver,
   writeBrowserVerificationAck,
@@ -40,6 +45,9 @@ const OPTION_SPEC = {
   quiet: { type: 'boolean' },
   ack: { type: 'boolean' },
   notes: { type: 'string' },
+  'probe-pack': { type: 'string' },
+  'no-boot': { type: 'boolean' },
+  'no-browser': { type: 'boolean' },
   help: { type: 'boolean' },
 };
 
@@ -61,6 +69,22 @@ Options:
   --quiet                   Suppress non-error confirmations.
   --ack                     Mark operatorAckAt on the latest record for
                             this FBS (used to clear a warn verdict).
+  --probe-pack <name>       Restrict this run to one blueprint-shipped
+                            probe pack by packName. When omitted, every
+                            discovered pack whose appliesTo() matches
+                            this FBS runs. Refuses (exit 2) when the
+                            name resolves to no discovered pack.
+  --no-browser              Skip the real headless browser (probe packs
+                            that call browser.* will see browser=null).
+                            Default: provision a headless browser via
+                            the pinned Playwright MCP so packs can drive
+                            real DOM interactions.
+  --no-boot                 Do not run a pack's declared bootCommand
+                            when the runtime URL is unreachable. Default:
+                            when any pack declares a boot block and the
+                            runtime is not answering, spawn bootCommand
+                            from the project root, wait for waitForUrl
+                            then waitForSelector, then run packs.
   --help                    Print this help.
 
 Exit codes:
@@ -163,13 +187,77 @@ export async function main(argv, deps = {}) {
         stderr.write('[error] usage browser-verify: no fetch available in the runtime; supply deps.fetch\n');
         return 2;
       }
-      record = await runAgentScreenshotCritique({
-        tree, fbs, runtimeUrl, runtimeProfile: profile,
-        browserDriver, fetch: fetchFn,
-        artefactDir: `.rcf/artefacts/${fbsId.toLowerCase()}`,
-        critiqueNotes: flags.notes,
-        now,
-      });
+      // Probe-pack discovery: gather packs from every applied blueprint
+      // on the manifest, then apply --probe-pack filter if any.
+      const appliedBlueprints = readAppliedBlueprints({ manifest: tree.manifest, projectRoot });
+      const { packs, errors: packErrors } = await loadProbePacks({ appliedBlueprints, projectRoot });
+      if (packErrors.length > 0) {
+        for (const e of packErrors) stderr.write(`[error] usage browser-verify: probe-pack loader refused ${e.packAbsPath}: ${e.message}\n`);
+        return 2;
+      }
+      const packNameFilter = typeof flags['probe-pack'] === 'string' && flags['probe-pack'].length > 0
+        ? flags['probe-pack']
+        : undefined;
+      if (packNameFilter && !packs.some((p) => p.packName === packNameFilter)) {
+        const discovered = packs.map((p) => p.packName).sort();
+        stderr.write(`[error] usage browser-verify: --probe-pack '${packNameFilter}' resolves to no discovered pack. Discovered packs: ${discovered.length === 0 ? '(none)' : discovered.join(', ')}.\n`);
+        return 2;
+      }
+
+      const filteredPacks = packNameFilter
+        ? packs.filter((p) => p.packName === packNameFilter)
+        : packs;
+      const provisionBrowser = deps.createPackBrowser ?? createPackBrowser;
+      const bootProbe = deps.bootIfNeeded ?? bootIfNeeded;
+
+      let packBrowser = deps.packBrowser ?? null;
+      const cleanups = [];
+      try {
+        if (packBrowser === null && filteredPacks.length > 0 && !flags['no-browser']) {
+          packBrowser = await provisionBrowser({
+            projectRoot,
+            logger: (line) => { if (!flags.quiet) stderr.write(`${line}\n`); },
+          });
+          cleanups.push(async () => { try { await packBrowser.close(); } catch { /* fine */ } });
+        }
+
+        if (!flags['no-boot'] && filteredPacks.length > 0) {
+          const boot = pickBootFromPacks(filteredPacks);
+          if (boot) {
+            const bootOutcome = await bootProbe({
+              boot,
+              runtimeUrl,
+              projectRoot,
+              fetch: fetchFn,
+              browser: packBrowser,
+              logger: (line) => { if (!flags.quiet) stderr.write(`${line}\n`); },
+            });
+            for (const n of bootOutcome.notes) if (!flags.quiet) stderr.write(`[boot] ${n}\n`);
+            if (bootOutcome.started) {
+              cleanups.push(async () => { try { await bootOutcome.stop(); } catch { /* fine */ } });
+            }
+          }
+        }
+
+        record = await runAgentScreenshotCritique({
+          tree, fbs, runtimeUrl, runtimeProfile: profile,
+          browserDriver, fetch: fetchFn,
+          artefactDir: `.rcf/artefacts/${fbsId.toLowerCase()}`,
+          critiqueNotes: flags.notes,
+          probePacks: packs,
+          packBrowser,
+          packNameFilter,
+          projectRoot,
+          now,
+        });
+      } finally {
+        // LIFO cleanup: close browser before stopping the server so a
+        // page.close talking to a killed server never hangs the CLI.
+        while (cleanups.length > 0) {
+          const step = cleanups.pop();
+          try { await step(); } catch { /* fine */ }
+        }
+      }
     }
   } catch (err) {
     writeUnexpectedFailure(
@@ -203,6 +291,41 @@ export async function main(argv, deps = {}) {
   return record.verdict === 'pass' ? 0 : 4;
 }
 
+/**
+ * Read applied blueprints off the manifest as an array of
+ * `{ slug, absPath }` suitable for `loadProbePacks`.
+ *
+ * The applied-blueprint record carries a `source` field (see
+ * `src/blueprint/apply.js`). For a shelf apply the source is the
+ * shelf-relative slug; for a local-path apply it is an absolute
+ * path; for a library apply it is `<library>:<slug>`. We resolve
+ * to the shelf path shipped alongside the CLI package or, in the
+ * monorepo, the repo-root shelf. Missing directories are skipped
+ * without error (the CLI later checks discovered vs. requested).
+ */
+function readAppliedBlueprints({ manifest, projectRoot }) {
+  const list = Array.isArray(manifest?.blueprints) ? manifest.blueprints : [];
+  const out = [];
+  for (const entry of list) {
+    if (!entry || typeof entry.slug !== 'string' || entry.slug.length === 0) continue;
+    const absPath = resolveBlueprintAbsPath({ entry, projectRoot });
+    if (absPath) out.push({ slug: entry.slug, absPath });
+  }
+  return out;
+}
+
+function resolveBlueprintAbsPath({ entry, projectRoot }) {
+  const { slug, source } = entry;
+  if (typeof source === 'string' && source.length > 0) {
+    if (isAbsolute(source)) return source;
+    if (source.startsWith('./') || source.startsWith('../')) {
+      return resolve(projectRoot, source);
+    }
+  }
+  const cwd = resolve(projectRoot, 'blueprints', slug);
+  return cwd;
+}
+
 function defaultUrlForProfile(profile) {
   if (profile === 'ci') return 'http://127.0.0.1:3000';
   if (profile === 'deployed') return '';
@@ -227,5 +350,22 @@ function renderSummary({ stdout, record }) {
       stdout.write(`    [${c.verdict}] ${c.check} (status=${c.status ?? 'n/a'})${detail}\n`);
     }
   }
+  if (Array.isArray(record.probePacks) && record.probePacks.length > 0) {
+    stdout.write('  probe packs:\n');
+    for (const p of record.probePacks) {
+      if (p.applicable === false) {
+        stdout.write(`    [skip] ${p.packName} (${p.blueprintSlug}): ${p.detail ?? 'not applicable to this FBS'}\n`);
+        continue;
+      }
+      for (const pc of p.preChecks ?? []) {
+        const detail = pc.detail ? ` - ${pc.detail}` : '';
+        stdout.write(`    [${pc.verdict}] ${p.packName} pre-check ${pc.id}${detail}\n`);
+      }
+      for (const c of p.checks ?? []) {
+        const detail = c.detail ? ` - ${c.detail}` : '';
+        stdout.write(`    [${c.verdict}] ${p.packName} ${c.id}${detail}\n`);
+      }
+    }
+  }
   stdout.write(`  verdict: ${record.verdict}\n\n`);
 }

package/src/cli/create.js

@@ -37,6 +37,12 @@ const OPTION_SPEC = {
   path: { type: 'string' },
   deps: { type: 'string' },
   'derive-deps': { type: 'boolean' },
+  // rcf-eval-node spec section 2.2: `rcf define create ac
+  // --determinism deterministic|nonDeterministic`. Optional at CLI
+  // (default deterministic; absence is treated as `deterministic` by
+  // every consumer). A value outside the enum exits 2 with the spec-
+  // named message (spec section 8).
+  determinism: { type: 'string' },
 };
 
 export const HELP = `Usage: rcf define create <kind> [options]
@@ -202,6 +208,14 @@ export async function main(argv, deps = {}) {
       stderr.write(`[error] usage create ${kind}: --description is required\n`);
       return 2;
     }
+    // rcf-eval-node spec section 2.2 + 8: --determinism enum guard.
+    if (kind === 'ac' && flags.determinism !== undefined) {
+      if (flags.determinism !== 'deterministic' && flags.determinism !== 'nonDeterministic') {
+        stderr.write(`--determinism expects 'deterministic' or 'nonDeterministic', got '${flags.determinism}'\n`);
+        return 2;
+      }
+      body.determinism = flags.determinism;
+    }
   } else if (kind === 'cn') {
     if (!body.path) {
       stderr.write('[error] usage create cn: --path is required\n');

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 };