rcf-lite 0.19.0 → 0.20.0

package/src/eval/judge.js

@@ -0,0 +1,338 @@
+// LLM-as-judge run path for an EVAL. rcf-eval-node spec 2026-09-04
+// section 6: `judge.type: llmJudge` runs by spawning `claude` (or
+// `codex`) on PATH under subscription auth, capturing structured JSON
+// on stdout, validating against the declared response schema, and
+// appending a runRecord[] entry on the EVAL document.
+//
+// Estate rule (banked): every model call goes through the `claude` or
+// `codex` CLI. No API keys, no HTTP fetches into rcf-lite. The verify
+// launcher demonstrates the shape today (spawn `claude` by bare name).
+//
+// This module is invocation-only: the spawn contract, stdout capture,
+// schema validation, and runRecord append. Case orchestration
+// (walking cases[], rolling up per-case scores, applying critical-must-
+// pass) is intentionally minimal at v1 (spec: v1 ships one canonical
+// invocation, not a full runner).
+
+import { readFile } from 'node:fs/promises';
+import { spawn } from 'node:child_process';
+
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+
+import { rcfError } from '#core/errors';
+
+const RESPONSE_ENVELOPE_HINT = {
+  type: 'object',
+  required: ['perCriterion'],
+  properties: {
+    perCriterion: {
+      type: 'array',
+      items: {
+        type: 'object',
+        required: ['id', 'score'],
+        properties: {
+          id: { type: 'string' },
+          score: { type: 'number', minimum: 0, maximum: 1 },
+          rationale: { type: 'string' },
+          criticalPass: { type: 'boolean' },
+        },
+      },
+    },
+    aggregateScore: { type: 'number', minimum: 0, maximum: 1 },
+  },
+};
+
+/**
+ * @typedef {object} RunOneCaseArgs
+ * @property {object} evalDoc              the EVAL document
+ * @property {object} caseDoc              one entry from evalDoc.cases[]
+ * @property {string} projectRoot          absolute project root
+ * @property {string} [systemPromptText]   the resolved system prompt text
+ * @property {object} [responseSchema]     the resolved response schema
+ * @property {function} [spawnImpl]        seam for tests
+ * @property {number} [timeoutMs]          default 60_000
+ */
+
+/**
+ * Load the harness system prompt and response schema for an EVAL, from
+ * `judge.harness.systemPromptPath` and `judge.harness.responseSchemaPath`
+ * (paths relative to the project root). Returns a structured error
+ * when either cannot be read or the schema is not valid JSON.
+ *
+ * @param {object} args
+ * @param {object} args.evalDoc
+ * @param {string} args.projectRoot
+ * @returns {Promise<{ systemPromptText: string|null, responseSchema: object|null } | import('#core/errors').RcfError>}
+ */
+export async function loadJudgeHarness({ evalDoc, projectRoot }) {
+  const harness = evalDoc?.judge?.harness;
+  if (!harness) {
+    return { systemPromptText: null, responseSchema: RESPONSE_ENVELOPE_HINT };
+  }
+  let systemPromptText = null;
+  if (typeof harness.systemPromptPath === 'string') {
+    try {
+      systemPromptText = await readFile(`${projectRoot}/${harness.systemPromptPath}`, 'utf8');
+    } catch (err) {
+      return rcfError({
+        kind: 'ioFailure',
+        message: `eval judge: could not read systemPromptPath ${harness.systemPromptPath}: ${err.message}`,
+        filePath: harness.systemPromptPath,
+      });
+    }
+  }
+  let responseSchema = null;
+  if (typeof harness.responseSchemaPath === 'string') {
+    try {
+      const raw = await readFile(`${projectRoot}/${harness.responseSchemaPath}`, 'utf8');
+      responseSchema = JSON.parse(raw);
+    } catch (err) {
+      return rcfError({
+        kind: 'parseFailure',
+        message: `eval judge: could not read/parse responseSchemaPath ${harness.responseSchemaPath}: ${err.message}`,
+        filePath: harness.responseSchemaPath,
+      });
+    }
+  }
+  return { systemPromptText, responseSchema: responseSchema ?? RESPONSE_ENVELOPE_HINT };
+}
+
+/**
+ * Run one case through the LLM judge. Spawns the invoker CLI (`claude`
+ * by default; `codex` for consumers on the codex leg) with the system
+ * prompt via `-p` and the case payload on stdin. Captures stdout,
+ * validates against the response schema, and returns the parsed graded
+ * result. Model-hint is passed via `--model` when supplied by the
+ * harness; otherwise the CLI's default model resolves.
+ *
+ * @param {RunOneCaseArgs} args
+ * @returns {Promise<{ graded: object, invoker: string, modelHintUsed: string|null, rawStdout: string } | import('#core/errors').RcfError>}
+ */
+export async function runOneCase(args) {
+  const {
+    evalDoc, caseDoc,
+    systemPromptText = null,
+    responseSchema = RESPONSE_ENVELOPE_HINT,
+    spawnImpl = spawn,
+    timeoutMs = 60_000,
+  } = args;
+  const harness = evalDoc?.judge?.harness;
+  if (!harness) {
+    return rcfError({
+      kind: 'usage',
+      message: 'eval judge: judge.harness is required for llmJudge',
+      documentId: evalDoc?.id,
+      field: 'judge.harness',
+    });
+  }
+  const invoker = harness.invoker;
+  if (invoker !== 'claude' && invoker !== 'codex') {
+    return rcfError({
+      kind: 'usage',
+      message: `eval judge: unsupported invoker '${invoker}' (expected 'claude' or 'codex')`,
+      documentId: evalDoc?.id,
+      field: 'judge.harness.invoker',
+    });
+  }
+
+  const payload = {
+    caseId: caseDoc?.id ?? null,
+    input: caseDoc?.input ?? null,
+    ...(caseDoc?.expected !== undefined ? { expected: caseDoc.expected } : {}),
+    criteria: (evalDoc.criteria ?? []).map((c) => ({
+      id: c.id,
+      description: c.description,
+      critical: Boolean(c.critical),
+    })),
+    criteriaIds: caseDoc?.criteriaIds ?? [],
+    notes: caseDoc?.notes ?? '',
+  };
+  const stdinText = JSON.stringify(payload);
+  const argv = [];
+  if (systemPromptText) argv.push('-p', systemPromptText);
+  if (typeof harness.modelHint === 'string' && harness.modelHint.length > 0) {
+    argv.push('--model', harness.modelHint);
+  }
+  argv.push('--output-format', 'json');
+
+  const outcome = await spawnAndCollect(invoker, argv, stdinText, { spawnImpl, timeoutMs });
+  if ('kind' in outcome && outcome.kind === 'ioFailure') return outcome;
+
+  let graded;
+  try {
+    graded = JSON.parse(outcome.stdout.trim());
+  } catch (err) {
+    return rcfError({
+      kind: 'parseFailure',
+      message: `eval judge: invoker '${invoker}' stdout did not parse as JSON: ${err.message}`,
+      documentId: evalDoc.id,
+    });
+  }
+  const ajv = new Ajv2020({ allErrors: true, strict: false });
+  addFormats(ajv);
+  const validate = ajv.compile(responseSchema);
+  if (!validate(graded)) {
+    const first = (validate.errors ?? [])[0];
+    return rcfError({
+      kind: 'validation',
+      message: `eval judge: response failed schema at ${first?.instancePath ?? '/'} ${first?.message ?? 'invalid'}`,
+      documentId: evalDoc.id,
+    });
+  }
+  return {
+    graded,
+    invoker,
+    modelHintUsed: harness.modelHint ?? null,
+    rawStdout: outcome.stdout,
+  };
+}
+
+/**
+ * Roll up per-case graded outputs into a runRecord[] entry. Aggregate
+ * score is the mean of perCriterion.score across cases (weighted by
+ * criterion.weight when supplied). Critical failures are aggregated
+ * from any case's perCriterion entry with criticalPass=false on a
+ * criterion declared critical.
+ *
+ * @param {object} args
+ * @param {object} args.evalDoc
+ * @param {Array<{ caseId: string, graded: object, modelHintUsed: string|null }>} args.cases
+ * @param {string} args.runner
+ * @param {Date} [args.now]
+ * @returns {object} runRecord entry
+ */
+export function composeRunRecord({ evalDoc, cases, runner, now = new Date() }) {
+  const criteriaById = new Map((evalDoc.criteria ?? []).map((c) => [c.id, c]));
+  const perCaseScores = [];
+  const criticalFailures = [];
+  let totalWeight = 0;
+  let weightedSum = 0;
+  for (const c of cases) {
+    const graded = c.graded ?? {};
+    const perCrit = Array.isArray(graded.perCriterion) ? graded.perCriterion : [];
+    let caseSum = 0;
+    let caseWeight = 0;
+    for (const entry of perCrit) {
+      const crit = criteriaById.get(entry.id);
+      const weight = typeof crit?.weight === 'number' && crit.weight > 0 ? crit.weight : 1;
+      const score = typeof entry.score === 'number' ? Math.max(0, Math.min(1, entry.score)) : 0;
+      caseWeight += weight;
+      caseSum += weight * score;
+      if (crit?.critical && entry.criticalPass === false) {
+        criticalFailures.push({ caseId: c.caseId, criterionId: entry.id });
+      }
+    }
+    const caseAggregate = caseWeight > 0 ? caseSum / caseWeight : 0;
+    // rcf-schemas 0.6.0 perCaseScore shape: { caseId, score } with
+    // additionalProperties false. Score is the weighted aggregate 0..1.
+    perCaseScores.push({ caseId: c.caseId, score: caseAggregate });
+    totalWeight += caseWeight;
+    weightedSum += caseSum;
+  }
+  const aggregateScore = totalWeight > 0 ? weightedSum / totalWeight : 0;
+  const passThreshold = evalDoc.passThreshold ?? {};
+  const criticalMustPass = passThreshold.criticalMustPass !== false;
+  const meetsAggregate = aggregateScore >= (typeof passThreshold.aggregateScore === 'number' ? passThreshold.aggregateScore : 0.85);
+  const criticalOk = !(criticalMustPass && criticalFailures.length > 0);
+  const verdict = meetsAggregate && criticalOk ? 'pass' : 'fail';
+  const modelPinned = cases.find((c) => c.modelHintUsed)?.modelHintUsed ?? null;
+  const record = {
+    runId: `${now.toISOString()}-${Math.random().toString(36).slice(2, 6)}`,
+    runAt: now.toISOString(),
+    runner,
+    aggregateScore,
+    criticalFailures,
+    perCaseScores,
+    verdict,
+  };
+  if (modelPinned) record.modelPinned = modelPinned;
+  return record;
+}
+
+/**
+ * Append a runRecord[] entry to an EVAL document.
+ *
+ * @param {object} args
+ * @param {object} args.evalDoc
+ * @param {object} args.runRecord
+ * @returns {object} updated evalDoc (new object; caller writes it)
+ */
+export function appendRunRecord({ evalDoc, runRecord }) {
+  const runs = Array.isArray(evalDoc.runRecord) ? evalDoc.runRecord : [];
+  return {
+    ...evalDoc,
+    runRecord: [...runs, runRecord],
+    updatedAt: new Date().toISOString(),
+  };
+}
+
+/**
+ * Spawn the invoker and collect stdout / stderr. Returns
+ * `{ stdout, stderr, code }` on success, or a rcfError on failure.
+ *
+ * @param {string} invoker
+ * @param {string[]} argv
+ * @param {string} stdinText
+ * @param {{ spawnImpl?: function, timeoutMs?: number }} opts
+ * @returns {Promise<{ stdout: string, stderr: string, code: number|null } | import('#core/errors').RcfError>}
+ */
+export function spawnAndCollect(invoker, argv, stdinText, { spawnImpl = spawn, timeoutMs = 60_000 } = {}) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawnImpl(invoker, argv, { stdio: ['pipe', 'pipe', 'pipe'] });
+    } catch (err) {
+      resolve(rcfError({
+        kind: 'ioFailure',
+        message: `eval judge: failed to spawn '${invoker}': ${err.message}`,
+      }));
+      return;
+    }
+    let stdout = '';
+    let stderr = '';
+    let done = false;
+    const timer = setTimeout(() => {
+      done = true;
+      try { child.kill('SIGTERM'); } catch { /* ignore */ }
+      resolve(rcfError({
+        kind: 'ioFailure',
+        message: `eval judge: invoker '${invoker}' timed out after ${timeoutMs}ms`,
+      }));
+    }, timeoutMs);
+    child.stdout.on('data', (chunk) => { stdout += String(chunk); });
+    child.stderr.on('data', (chunk) => { stderr += String(chunk); });
+    child.on('error', (err) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      resolve(rcfError({
+        kind: 'ioFailure',
+        message: `eval judge: invoker '${invoker}' error: ${err.message}`,
+      }));
+    });
+    child.on('close', (code) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      if (code !== 0) {
+        resolve(rcfError({
+          kind: 'ioFailure',
+          message: `eval judge: invoker '${invoker}' exited with code ${code}: ${stderr.slice(0, 400)}`,
+        }));
+        return;
+      }
+      resolve({ stdout, stderr, code });
+    });
+    try {
+      child.stdin.end(stdinText);
+    } catch (err) {
+      done = true;
+      clearTimeout(timer);
+      resolve(rcfError({
+        kind: 'ioFailure',
+        message: `eval judge: writing stdin to '${invoker}' failed: ${err.message}`,
+      }));
+    }
+  });
+}

package/src/finalise/index.js

@@ -22,9 +22,17 @@ export {
   // 0.8.0 slug-train car 4: NV-BL-GATE-01 pull-in of the profile-vs-AC
   // scope-mismatch check into REVIEW.
   findScopeMismatchAcs, reportHasScopeMismatch,
+  // rcf-eval-node spec 2026-09-04 sections 5.2 + 8: EVAL-MISSING and
+  // EVAL-BELOW-THRESHOLD refusal on `rcf finalise`.
+  findEvalRefusalAcs, reportHasEvalRefusal,
 } from './ingest.js';
 export {
   composeShipWithoutVerifiedRecord,
   nextShipWithoutVerifiedId,
   writeShipWithoutVerifiedRecord,
 } from './ship-without-verified.js';
+export {
+  composeShipWithoutEvalRecord,
+  nextShipWithoutEvalId,
+  writeShipWithoutEvalRecord,
+} from './ship-without-eval.js';

package/src/finalise/ingest.js

@@ -158,3 +158,30 @@ export function findScopeMismatchAcs(report) {
 export function reportHasScopeMismatch(report) {
   return findScopeMismatchAcs(report).length > 0;
 }
+
+/**
+ * rcf-eval-node spec 2026-09-04 sections 5.2 + 8: extract per-AC
+ * verdicts in {EVAL-MISSING, EVAL-BELOW-THRESHOLD} from a verify
+ * report. Both refuse `rcf finalise` promotion to `verified` unless
+ * the operator opts out via `--ship-without-eval "<reason>"`.
+ *
+ * @param {object} report
+ * @returns {Array<{ acId: string, verdict: string, reason?: string }>}
+ */
+export function findEvalRefusalAcs(report) {
+  const perAc = Array.isArray(report?.perAcVerdicts) ? report.perAcVerdicts : [];
+  return perAc
+    .filter((e) => e && (e.verdict === 'EVAL-MISSING' || e.verdict === 'EVAL-BELOW-THRESHOLD'))
+    .map((e) => ({ acId: e.acId, verdict: e.verdict, reason: e.reason }));
+}
+
+/**
+ * True when a verify report carries at least one EVAL-MISSING or
+ * EVAL-BELOW-THRESHOLD verdict.
+ *
+ * @param {object} report
+ * @returns {boolean}
+ */
+export function reportHasEvalRefusal(report) {
+  return findEvalRefusalAcs(report).length > 0;
+}

package/src/finalise/ship-without-eval.js

@@ -0,0 +1,123 @@
+// Ship-without-eval acknowledgement writer. Sister of
+// ship-without-verified.js. rcf-eval-node spec 2026-09-04 sections 5.2
+// and 8: `rcf finalise --ship-without-eval "<reason>"` acknowledges
+// EVAL-MISSING / EVAL-BELOW-THRESHOLD per-AC verdicts on a verify
+// report and lets finalise proceed with an audit-log entry.
+//
+// Landing shape mirrors ship-without-verified: an optional
+// `shipWithoutEval[]` array on the manifest, with monotonic ids
+// `swe-<fbsId>-<n>`, the operator's reason string, the declared AC
+// verdicts, the report path, and an ISO timestamp. rcf-schemas 0.6.0
+// does not yet declare this field on the manifest schema; consumers
+// treat its absence as "no acks" and its presence as data.
+
+import { mkdir, rename, unlink, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+
+import { rcfError } from '#core/errors';
+
+/**
+ * @typedef {object} ShipWithoutEvalDeclaredAc
+ * @property {string} acId
+ * @property {'EVAL-MISSING'|'EVAL-BELOW-THRESHOLD'} verdict
+ * @property {string} [reason]  reason as reported by the verdict layer
+ */
+
+/**
+ * @typedef {object} ShipWithoutEvalRecord
+ * @property {string} id            `swe-<fbsId>-<n>` monotonic per FBS.
+ * @property {string} fbsId
+ * @property {string} ackedAt       ISO timestamp.
+ * @property {string} reason        operator-supplied reason (--ship-without-eval "…").
+ * @property {ShipWithoutEvalDeclaredAc[]} declaredAcs  minItems 1.
+ * @property {string} reportPath
+ */
+
+/**
+ * Monotonic id allocator for the shipWithoutEval array. Mirrors
+ * `nextShipWithoutVerifiedId` (ship-without-verified.js).
+ *
+ * @param {object|null} manifest
+ * @param {string} fbsId
+ * @returns {string}
+ */
+export function nextShipWithoutEvalId(manifest, fbsId) {
+  const prefix = `swe-${fbsId}-`;
+  const existing = Array.isArray(manifest?.shipWithoutEval) ? manifest.shipWithoutEval : [];
+  let maxN = 0;
+  for (const rec of existing) {
+    if (typeof rec?.id !== 'string' || !rec.id.startsWith(prefix)) continue;
+    const n = Number.parseInt(rec.id.slice(prefix.length), 10);
+    if (Number.isFinite(n) && n > maxN) maxN = n;
+  }
+  return `${prefix}${maxN + 1}`;
+}
+
+/**
+ * Compose the ack record.
+ *
+ * @param {object} args
+ * @param {object|null} args.manifest
+ * @param {string} args.fbsId
+ * @param {string} args.reason
+ * @param {ShipWithoutEvalDeclaredAc[]} args.declaredAcs
+ * @param {string} args.reportPath
+ * @param {Date} [args.now]
+ * @returns {ShipWithoutEvalRecord}
+ */
+export function composeShipWithoutEvalRecord({
+  manifest, fbsId, reason, declaredAcs, reportPath, now = new Date(),
+}) {
+  return {
+    id: nextShipWithoutEvalId(manifest, fbsId),
+    fbsId,
+    ackedAt: now.toISOString(),
+    reason,
+    declaredAcs: declaredAcs.map((a) => {
+      const out = { acId: a.acId, verdict: a.verdict };
+      if (typeof a.reason === 'string' && a.reason.length > 0) out.reason = a.reason;
+      return out;
+    }),
+    reportPath,
+  };
+}
+
+/**
+ * Persist a ship-without-eval acknowledgement onto the manifest.
+ * Manifest write is atomic (tmp + rename). rcf-schemas 0.6.0's manifest
+ * schema does not declare this field, so the write path skips the
+ * validator (spec section 9: extensions land at a later minor).
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @param {object} args.tree
+ * @param {ShipWithoutEvalRecord} args.record
+ * @returns {Promise<{ record: ShipWithoutEvalRecord } | import('#core/errors').RcfError>}
+ */
+export async function writeShipWithoutEvalRecord({ projectRoot, tree, record }) {
+  const manifest = tree.manifest ?? {};
+  const nextManifest = { ...manifest };
+  const existing = Array.isArray(nextManifest.shipWithoutEval) ? nextManifest.shipWithoutEval : [];
+  nextManifest.shipWithoutEval = [...existing, record];
+
+  const absPath = join(projectRoot, 'rcf', 'manifest.json');
+  try {
+    await mkdir(dirname(absPath), { recursive: true });
+    const tmp = `${absPath}.tmp`;
+    await writeFile(tmp, `${JSON.stringify(nextManifest, null, 2)}\n`, 'utf8');
+    try {
+      await rename(tmp, absPath);
+    } catch (err) {
+      try { await unlink(tmp); } catch { /* ignore */ }
+      throw err;
+    }
+  } catch (err) {
+    return rcfError({
+      kind: 'ioFailure',
+      message: `finalise: ship-without-eval manifest write failed: ${err.message}`,
+      filePath: 'rcf/manifest.json',
+      stack: err.stack,
+    });
+  }
+  return { record };
+}

package/src/query/eval-coverage.js

@@ -0,0 +1,162 @@
+// Pure EVAL-coverage compute. Given a walker-produced TreeModel, walk
+// the REQ chain (PRD -> REQ -> US -> AC) and report, per AC, whether
+// its `determinism` classification requires an EVAL, whether an EVAL
+// binds it, and whether that EVAL is "resolving" per the spec (a
+// non-superseded EVAL whose most recent runRecord[] entry is not
+// `pending`).
+//
+// spec: `projects/rcf-lite-wsd/specs/rcf-eval-node-spec-2026-09-04.md`
+// sections 2.3 and 4. Determinism absence resolves to `deterministic`;
+// deterministic ACs are never gated by this audit. `--strict` refuses
+// only when a nonDeterministic AC lacks a resolving EVAL. Presence of
+// an EVAL on a deterministic AC is reported as `covered-optional`,
+// never as a defect.
+//
+// This module is pure and synchronous; the CLI layer walks the tree
+// and formats.
+
+/**
+ * @typedef {import('#core/store/walker.js').TreeModel} TreeModel
+ */
+
+/**
+ * @typedef {'deterministic'|'nonDeterministic'} Determinism
+ */
+
+/**
+ * @typedef {'resolving'|'pending'|'superseded'|'absent'} EvalStatus
+ */
+
+/**
+ * @typedef {object} AcEvalStatus
+ * @property {string} acId
+ * @property {string} usId
+ * @property {Determinism} determinism - absence resolves to 'deterministic'
+ * @property {EvalStatus} evalStatus
+ * @property {string|null} evalId - the resolving EVAL, if any; else null
+ * @property {string[]} evalIds - all EVALs whose acIds[] name this AC
+ * @property {'covered'|'covered-optional'|'missing'|'not-required'} outcome
+ *   - 'covered': nonDeterministic + resolving EVAL
+ *   - 'covered-optional': deterministic + resolving EVAL (informational)
+ *   - 'missing': nonDeterministic + no resolving EVAL
+ *   - 'not-required': deterministic + no EVAL
+ */
+
+/**
+ * @typedef {object} EvalCoverageReport
+ * @property {AcEvalStatus[]} acs - flat per-AC entries within scope
+ * @property {number} nonDeterministicCount
+ * @property {number} coveredCount - nonDeterministic with resolving EVAL
+ * @property {number} missingCount - nonDeterministic without resolving EVAL
+ * @property {boolean} ok - true when strict-gate passes: missingCount === 0
+ * @property {string|null} scopeId - null when tree-wide
+ */
+
+/**
+ * Determine the resolving status for one EVAL doc.
+ *
+ * Per spec 2.3, a "resolving" EVAL is:
+ *   - status is not 'superseded'
+ *   - runRecord[] has at least one entry whose verdict is not 'pending'
+ *
+ * @param {object} evalDoc
+ * @returns {EvalStatus}
+ */
+export function classifyEvalDoc(evalDoc) {
+  if (!evalDoc || typeof evalDoc !== 'object') return 'absent';
+  if (evalDoc.status === 'superseded') return 'superseded';
+  const records = Array.isArray(evalDoc.runRecord) ? evalDoc.runRecord : [];
+  if (records.length === 0) return 'pending';
+  // Latest record wins. `runAt` sorts lexicographically for ISO timestamps.
+  const sorted = [...records].sort((a, b) => (a?.runAt ?? '').localeCompare(b?.runAt ?? ''));
+  const latest = sorted[sorted.length - 1];
+  if (!latest || latest.verdict === 'pending') return 'pending';
+  return 'resolving';
+}
+
+/**
+ * @param {TreeModel} tree
+ * @param {object} [opts]
+ * @param {string|null} [opts.scopeId] - optional PRD / REQ / US id to scope
+ * @returns {EvalCoverageReport}
+ */
+export function computeEvalCoverage(tree, { scopeId = null } = {}) {
+  const usIds = collectScopedUsIds(tree, scopeId);
+  const acs = [];
+  for (const usId of usIds) {
+    const us = tree.byId.get(usId);
+    if (!us) continue;
+    for (const ac of us.acceptanceCriteria ?? []) {
+      const determinism = ac.determinism === 'nonDeterministic'
+        ? 'nonDeterministic'
+        : 'deterministic';
+      const evalIds = tree.evalByAcId?.get(ac.id) ?? [];
+      let outcome;
+      let evalStatus;
+      let resolvingId = null;
+      if (evalIds.length === 0) {
+        evalStatus = 'absent';
+        outcome = determinism === 'nonDeterministic' ? 'missing' : 'not-required';
+      } else {
+        // Pick the best status across bound EVALs. `resolving` beats
+        // `pending` beats `superseded`.
+        let bestRank = -1;
+        for (const evalId of evalIds) {
+          const evalDoc = tree.byId.get(evalId);
+          const cls = classifyEvalDoc(evalDoc);
+          const rank = cls === 'resolving' ? 3 : cls === 'pending' ? 2 : cls === 'superseded' ? 1 : 0;
+          if (rank > bestRank) {
+            bestRank = rank;
+            evalStatus = cls;
+            if (cls === 'resolving') resolvingId = evalId;
+          }
+        }
+        if (evalStatus === 'resolving') {
+          outcome = determinism === 'nonDeterministic' ? 'covered' : 'covered-optional';
+        } else {
+          outcome = determinism === 'nonDeterministic' ? 'missing' : 'not-required';
+        }
+      }
+      acs.push({
+        acId: ac.id,
+        usId,
+        determinism,
+        evalStatus,
+        evalId: resolvingId,
+        evalIds,
+        outcome,
+      });
+    }
+  }
+  const nonDeterministicCount = acs.filter((a) => a.determinism === 'nonDeterministic').length;
+  const missingCount = acs.filter((a) => a.outcome === 'missing').length;
+  const coveredCount = nonDeterministicCount - missingCount;
+  return {
+    acs,
+    nonDeterministicCount,
+    coveredCount,
+    missingCount,
+    ok: missingCount === 0,
+    scopeId,
+  };
+}
+
+/**
+ * Resolve the scope positional to the US ids it covers.
+ *
+ * @param {TreeModel} tree
+ * @param {string|null} scopeId
+ * @returns {string[]} US ids sorted ascending
+ */
+function collectScopedUsIds(tree, scopeId) {
+  const allUs = tree.userStories ?? [];
+  if (!scopeId) return allUs.map((u) => u.usId).sort();
+  const kind = tree.kindById.get(scopeId);
+  if (kind === 'userStory') return [scopeId];
+  if (kind === 'req') return allUs.filter((u) => u.reqId === scopeId).map((u) => u.usId).sort();
+  if (kind === 'prd') {
+    const reqIds = new Set((tree.requirements ?? []).filter((r) => r.prdId === scopeId).map((r) => r.reqId));
+    return allUs.filter((u) => reqIds.has(u.reqId)).map((u) => u.usId).sort();
+  }
+  return [];
+}