rcf-lite 0.0.1 → 0.8.0

package/src/cli/req-baseline.js

@@ -0,0 +1,269 @@
+// `rcf req-baseline <verb>` subcommand handler
+// (elicitation-and-playbook-hardening-0.7.0-spec §5).
+//
+// Verbs (spec §5.4 / §13.3):
+//   rcf req-baseline sweep [--req <id> | --all] [--dry-run] [--json] [--yes]
+//   rcf req-baseline sweep --status [--json]
+//   rcf req-baseline opt-out --req <id> --key <baselineKey> --reason "..." [--scope req|project]
+//   rcf req-baseline opt-out --remove --req <id> --key <baselineKey>
+//
+// The sweep proposes any baseline AC not yet present on a US under the
+// target REQ; the operator answers accept / opt-out / skip per candidate.
+// Silence is refused: candidates left undecided stay OPEN, and Stage 1
+// (rcf build --next) refuses any FBS binding an AC on a US that has
+// open sweeps (spec §5.4 + §5.5 canonical text).
+//
+// Non-interactive callers (--yes accept-all, --dry-run preview) are
+// legitimate; the moment-4 auto-enqueue path (spec §5.3) also produces
+// OPEN candidates that this verb resolves.
+
+import { parseArgs } from 'node:util';
+import { createInterface } from 'node:readline/promises';
+import process from 'node:process';
+
+import { walkTree } from '#core/store';
+
+import { findProjectRoot } from '../view/index.js';
+import {
+  planSweep,
+  applySweepDecisions,
+  writeOptOut,
+  removeOptOut,
+  listOpenCandidates,
+} from '../req-baseline/index.js';
+
+const OPTION_SPEC = {
+  req: { type: 'string' },
+  all: { type: 'boolean' },
+  key: { type: 'string' },
+  reason: { type: 'string' },
+  scope: { type: 'string' },
+  remove: { type: 'boolean' },
+  status: { type: 'boolean' },
+  'dry-run': { type: 'boolean' },
+  yes: { type: 'boolean' },
+  json: { type: 'boolean' },
+  quiet: { type: 'boolean' },
+  help: { type: 'boolean' },
+};
+
+export const HELP = `Usage: rcf req-baseline <verb> [options]
+
+Verbs:
+  sweep [--req <id> | --all] [--status] [--dry-run] [--yes] [--json]
+                             Walk every US under the target REQ (or all
+                             classified REQs) and propose any baseline
+                             ACs not yet present. Interactive by default
+                             on a TTY; --yes accepts every candidate;
+                             --dry-run prints the plan without writing.
+                             --status prints the open-candidate list
+                             (silence-refuses-build queue) without
+                             prompting.
+
+  opt-out --req <id> --key <baselineKey> --reason "..." [--scope req|project]
+                             Record an operator ruling that removes a
+                             baseline AC from the REQ (or the whole
+                             project) and inherit the ruling on future
+                             sweeps. Reason is at least 20 characters
+                             (schema-enforced).
+
+  opt-out --remove --req <id> --key <baselineKey>
+                             Delete an existing opt-out; the next sweep
+                             will re-propose the AC.
+
+Options:
+  --req <id>                 REQ to target
+  --all                      Target every classified REQ in the tree
+  --key <baselineKey>        Catalogue key (for example, auth.htmlLoginPage)
+  --reason "..."             Operator ruling (at least 20 characters)
+  --scope req|project        Opt-out scope; defaults to req
+  --dry-run                  Preview only, do not write
+  --yes                      Accept every proposed candidate (non-interactive)
+  --status                   Show open-sweep candidates without prompting
+  --json                     Emit machine-readable output
+  --quiet                    Suppress non-error confirmations
+  --help                     Print this help
+
+Exit codes:
+  0  success
+  2  usage error (unknown flag, missing --req, no project root)
+  3  validation failure on the written manifest
+  4  refused (opt-out reason below the 20-character floor)
+`;
+
+/**
+ * @param {string[]} argv
+ * @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; }
+  if (positionals.length === 0) {
+    stderr.write('[error] usage req-baseline: missing verb (sweep|opt-out)\n');
+    stderr.write(HELP);
+    return 2;
+  }
+  const verb = positionals[0];
+  if (!['sweep', 'opt-out'].includes(verb)) {
+    stderr.write(`[error] usage req-baseline: unknown verb ${verb} (expected sweep|opt-out)\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 walkResult = await walkTree({ projectRoot });
+  if (walkResult.errors.length > 0) {
+    stderr.write(`[warn] tree has ${walkResult.errors.length} pre-existing issue(s); proceeding - writes are validated against the post-write state (run 'rcf validate' for details)\n`);
+  }
+
+  if (verb === 'sweep') {
+    if (flags.status) {
+      const open = listOpenCandidates(walkResult.tree, { reqId: flags.req ?? null });
+      if (flags.json) {
+        stdout.write(`${JSON.stringify(open, null, 2)}\n`);
+        return 0;
+      }
+      if (open.length === 0) {
+        stdout.write('no open baseline sweep candidates\n');
+        return 0;
+      }
+      for (const item of open) {
+        stdout.write(`${item.usId} (${item.reqId}) open: ${item.baselineKeys.join(', ')}\n`);
+      }
+      return 0;
+    }
+
+    if (!flags.req && !flags.all) {
+      stderr.write('[error] usage req-baseline sweep: --req <id> or --all is required\n');
+      return 2;
+    }
+
+    const plan = planSweep(walkResult.tree, { reqId: flags.req ?? null, all: Boolean(flags.all) });
+    if (plan.candidates.length === 0) {
+      if (!flags.quiet) stdout.write('no baseline candidates to propose\n');
+      return 0;
+    }
+
+    if (flags['dry-run']) {
+      if (flags.json) {
+        stdout.write(`${JSON.stringify(plan, null, 2)}\n`);
+      } else {
+        for (const c of plan.candidates) {
+          stdout.write(`[dry-run] would propose ${c.baselineKey} on ${c.usId} (${c.reqId})\n`);
+        }
+      }
+      return 0;
+    }
+
+    // Resolve decisions.
+    const decisions = [];
+    if (flags.yes) {
+      for (const c of plan.candidates) decisions.push({ candidate: c, action: 'accept' });
+    } else {
+      const isTty = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+      if (!isTty) {
+        // Non-interactive with no --yes: leave every candidate OPEN. This
+        // matches the moment-4 auto-enqueue posture (spec §5.3): a
+        // baseline-blind US never silently ships; the operator must
+        // resolve open sweeps before Stage 1 accepts an FBS binding it.
+        if (!flags.quiet) stdout.write(`sweep left ${plan.candidates.length} candidate(s) OPEN (non-interactive; rerun with --yes to accept every candidate)\n`);
+        return 0;
+      }
+      const rl = createInterface({ input: process.stdin, output: process.stdout });
+      for (const c of plan.candidates) {
+        stdout.write(`\nREQ ${c.reqId} (${c.reqShape}) baseline for US ${c.usId}:\n`);
+        stdout.write(`  ${c.baselineKey}: ${c.canonicalText}\n`);
+        // eslint-disable-next-line no-await-in-loop
+        const ans = (await rl.question('[a]ccept / [o]pt-out / [s]kip? ')).trim().toLowerCase();
+        if (ans === 'a' || ans === 'accept') {
+          decisions.push({ candidate: c, action: 'accept' });
+        } else if (ans === 'o' || ans === 'opt-out') {
+          // eslint-disable-next-line no-await-in-loop
+          const reason = (await rl.question('reason (>= 20 chars): ')).trim();
+          if (reason.length < 20) {
+            stderr.write(`[error] refused opt-out: reason below 20-character floor for ${c.baselineKey}; leaving candidate OPEN\n`);
+            continue;
+          }
+          decisions.push({ candidate: c, action: 'opt-out', reason });
+        } else {
+          // skip: leaves the candidate OPEN.
+        }
+      }
+      rl.close();
+    }
+
+    const result = await applySweepDecisions({ projectRoot, tree: walkResult.tree, decisions });
+    if (result && result.kind && typeof result.message === 'string') {
+      stderr.write(`[error] ${result.kind} ${result.message}\n`);
+      return 3;
+    }
+    if (flags.json) {
+      stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+      return 0;
+    }
+    if (!flags.quiet) {
+      stdout.write(`sweep: ${result.accepted} accepted, ${result.optedOut} opted out, ${result.left} left OPEN\n`);
+    }
+    return 0;
+  }
+
+  // verb === 'opt-out'
+  if (flags.remove) {
+    if (!flags.req || !flags.key) {
+      stderr.write('[error] usage req-baseline opt-out --remove: --req and --key are required\n');
+      return 2;
+    }
+    const result = await removeOptOut({ projectRoot, tree: walkResult.tree, reqId: flags.req, baselineKey: flags.key });
+    if (result && result.kind && typeof result.message === 'string') {
+      stderr.write(`[error] ${result.kind} ${result.message}\n`);
+      return 3;
+    }
+    if (!flags.quiet) stdout.write(`opt-out removed for ${flags.req} ${flags.key}${result.removed ? '' : ' (no matching record found)'}\n`);
+    return 0;
+  }
+  if (!flags.req || !flags.key || !flags.reason) {
+    stderr.write('[error] usage req-baseline opt-out: --req, --key and --reason are required\n');
+    return 2;
+  }
+  if (flags.reason.length < 20) {
+    stderr.write(`[error] refused opt-out: --reason below 20-character floor (got ${flags.reason.length} chars); a one-word answer reads as silence, which is exactly what this ledger exists to prevent\n`);
+    return 4;
+  }
+  const scope = flags.scope ?? 'req';
+  if (!['req', 'project'].includes(scope)) {
+    stderr.write(`[error] usage req-baseline opt-out: --scope must be req or project (got ${scope})\n`);
+    return 2;
+  }
+  const result = await writeOptOut({
+    projectRoot,
+    tree: walkResult.tree,
+    reqId: flags.req,
+    baselineKey: flags.key,
+    reason: flags.reason,
+    scope,
+  });
+  if (result && result.kind && typeof result.message === 'string') {
+    stderr.write(`[error] ${result.kind} ${result.message}\n`);
+    return 3;
+  }
+  if (!flags.quiet) stdout.write(`opt-out ${result.id} recorded for ${flags.req} ${flags.key} (scope=${scope})\n`);
+  return 0;
+}

package/src/cli/req-classify.js

@@ -0,0 +1,135 @@
+// `rcf req-classify <req-id>` subcommand handler
+// (elicitation-and-playbook-hardening-0.7.0-spec §4.4).
+//
+// Reruns the REQ-shape classifier for one REQ (or all REQs when
+// --all is passed) and writes the resulting shapeClassification block
+// back onto the REQ. Useful after the pattern-set version bumps or when
+// the operator has updated a description and wants to re-check.
+
+import { parseArgs } from 'node:util';
+
+import { formatErrors, writeUnexpectedFailure, rcfError } from '#core/errors';
+import { walkTree } from '#core/store';
+
+import { findProjectRoot } from '../view/index.js';
+import { classifyAndPersistReq } from '../req-detection/index.js';
+
+const OPTION_SPEC = {
+  all: { type: 'boolean' },
+  json: { type: 'boolean' },
+  quiet: { type: 'boolean' },
+  help: { type: 'boolean' },
+};
+
+export const HELP = `Usage: rcf req-classify <req-id> [options]
+       rcf req-classify --all [options]
+
+Rerun the REQ-shape classifier for one requirement (or every requirement
+in the tree with --all) and write the resulting shapeClassification
+block back onto the REQ.
+
+Reads REQ title, description and rationale plus the parent PRD's intent
+and problem as fallback context; matches against the versioned pattern
+set in #core/patterns/req-shapes and writes shapes,
+signals and classifiedAt. Preserves any prior operatorOverride block.
+
+Options:
+  --all             Classify every REQ in the tree
+  --json            Emit the classification block as JSON on stdout
+  --quiet           Suppress non-error confirmations
+  --help            Print this help
+
+Exit codes:
+  0  success (or nothing to classify)
+  2  usage error (unknown id, no project root, bad flags)
+  3  validation failure on the merged REQ document
+`;
+
+/**
+ * @param {string[]} argv
+ * @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 useAll = Boolean(flags.all);
+  if (useAll && positionals.length > 0) {
+    stderr.write('[error] usage req-classify: --all takes no positional\n');
+    return 2;
+  }
+  if (!useAll && positionals.length !== 1) {
+    stderr.write('[error] usage req-classify: expected exactly one <req-id> (or --all)\n');
+    stderr.write(HELP);
+    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 walkResult = await walkTree({ projectRoot });
+  if (walkResult.errors.length > 0) {
+    stderr.write(`[warn] tree has ${walkResult.errors.length} pre-existing issue(s); proceeding - writes are validated against the post-write state (run 'rcf validate' for details)\n`);
+  }
+
+  const reqIds = [];
+  if (useAll) {
+    for (const [id, kind] of walkResult.tree.kindById) {
+      if (kind === 'requirement') reqIds.push(id);
+    }
+    reqIds.sort();
+  } else {
+    reqIds.push(positionals[0]);
+  }
+
+  /** @type {Array<{ reqId: string, block: object|null, changed: boolean }>} */
+  const results = [];
+  for (const reqId of reqIds) {
+    const outcome = await classifyAndPersistReq({
+      projectRoot,
+      tree: walkResult.tree,
+      reqId,
+    });
+    if (!outcome.ok) {
+      stderr.write(`[error] ${outcome.message}\n`);
+      return 3;
+    }
+    results.push({ reqId, block: outcome.block, changed: outcome.changed });
+  }
+
+  if (flags.json) {
+    stdout.write(`${JSON.stringify(results, null, 2)}\n`);
+    return 0;
+  }
+  if (!flags.quiet) {
+    for (const r of results) {
+      const verdict = r.block?.shapes?.join(', ') || 'none';
+      const reason = r.block?.reason ?? 'unknown';
+      const state = r.changed ? 'classified' : 'unchanged';
+      stdout.write(`${r.reqId}: shapes=[${verdict}] reason=${reason} (${state})\n`);
+    }
+  }
+  return 0;
+}
+
+// Silence linter on unused imports where the CLI helper does not need
+// the RcfError formatters directly today; they are the canonical import
+// surface for future error-path expansion.
+void formatErrors; void writeUnexpectedFailure; void rcfError;

package/src/cli/review.js

@@ -0,0 +1,295 @@
+// `rcf review <fbs-id>` subcommand handler
+// (verification-integrity-cluster-spec §5.5, §6).
+//
+// Runs the REVIEW-stage audit (test-theatre + mutation-sampling),
+// writes the reviewAudit record to the manifest, and exits with:
+//   0 on pass
+//   4 on warn or block
+//   3 on schema/tree validation failure
+//   1 on IO / unexpected runtime failure
+//   2 on usage error
+//
+// The mutation-sampling agent is injected via `deps.mutationRunner`;
+// v1 default is a no-op runner that emits a valid schema record with
+// a `notes` explaining that no runner was wired. `--skip-mutation`
+// records the skip explicitly. `--dry-run` runs the audit without
+// writing the record.
+
+import { access, mkdir, readdir, rename, unlink, writeFile } from 'node:fs/promises';
+import { join, dirname, relative } from 'node:path';
+import { parseArgs } from 'node:util';
+import process from 'node:process';
+
+import { rcfError, writeUnexpectedFailure } from '#core/errors';
+import { resolveTestPointers, validateDocument, walkTree } from '#core/store';
+
+import { findProjectRoot } from '../view/index.js';
+import {
+  auditTestTheatre,
+  composeReviewAuditRecord,
+} from '../review/index.js';
+import { auditUiBaselineDrift } from '../review/ui-baseline-drift.js';
+import {
+  defaultMutationRunner,
+  defaultSizing,
+  resolveTestCommand,
+  skippedMutationRunner,
+} from '../review/mutation.js';
+
+const OPTION_SPEC = {
+  'dry-run': { type: 'boolean' },
+  json: { type: 'boolean' },
+  'skip-mutation': { type: 'boolean' },
+  'test-cmd': { type: 'string' },
+  quiet: { type: 'boolean' },
+  help: { type: 'boolean' },
+};
+
+export const HELP = `Usage: rcf review <fbs-id> [options]
+
+Run the REVIEW-stage audit (test-theatre + mutation-sampling) and write
+the reviewAudit record to the manifest. Exit 4 on any warn or block
+verdict, so the audit is a Stage 3 -> Stage 4 gate.
+
+Options:
+  --dry-run                 Run the audit and print findings without
+                            writing the reviewAudit record.
+  --json                    Emit the composed record to stdout as JSON.
+  --skip-mutation           Record that mutation-sampling was skipped
+                            without running it; useful when the harness
+                            has no runner wired yet. The reviewAudit
+                            record still validates.
+  --test-cmd <command>      Test command for the mutation-sampling agent
+                            (default: manifest.testCommand, else
+                            'npm test' when package.json exists).
+  --quiet                   Suppress non-error stdout
+  --help                    Print this help
+
+Exit codes:
+  0  audit passed
+  1  IO / unexpected runtime failure
+  2  usage error
+  3  schema or tree validation refused the write
+  4  audit warn or block verdict (Stage 4 refused)
+`;
+
+/**
+ * @param {string[]} argv
+ * @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;
+  if (flags.help) { stdout.write(HELP); return 0; }
+  if (parsed.positionals.length !== 1) {
+    stderr.write('[error] usage review: expected exactly one <fbs-id> positional\n');
+    return 2;
+  }
+  const fbsId = parsed.positionals[0];
+  if (!/^FBS-\d{3,}$/.test(fbsId)) {
+    stderr.write(`[error] usage review: expected an FBS id like FBS-011, got '${fbsId}'\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).\n');
+    return 2;
+  }
+
+  const walkResult = await walkTree({ projectRoot });
+  if (walkResult.errors.length > 0) {
+    stderr.write(`[warn] tree has ${walkResult.errors.length} pre-existing issue(s); the audit proceeds but coverage-drift findings may be noisy\n`);
+  }
+  const tree = walkResult.tree;
+  const fbs = tree.byId.get(fbsId);
+  if (!fbs || tree.kindById.get(fbsId) !== 'fbs') {
+    stderr.write(`[error] usage review: ${fbsId} not found or not an FBS\n`);
+    return 2;
+  }
+
+  // Test-pointer resolution feeds the testPointerBroken detector.
+  const testPointers = await resolveTestPointers({ projectRoot, tree });
+  const findings = auditTestTheatre({ tree, fbs, testPointers });
+
+  // Track B (ui-design-gate-0.7.0-spec §3.4): run the UI-baseline drift
+  // audit alongside the Track A test-theatre audit for uiBearing FBS.
+  // One brief, one worker, one record per FBS: the same reviewAudit
+  // record carries both Track A and Track B kinds (spec §12 O-12).
+  const listFiles = deps.listFiles ?? defaultListFiles(projectRoot);
+  const uiFindings = await auditUiBaselineDrift({
+    projectRoot,
+    fbs,
+    uiBaseline: tree.manifest?.uiBaseline ?? null,
+    listFiles,
+  });
+  for (const f of uiFindings) findings.push(f);
+
+  // Mutation-sampling.
+  let mutationRunner = deps.mutationRunner;
+  if (!mutationRunner) mutationRunner = flags['skip-mutation'] ? skippedMutationRunner : defaultMutationRunner;
+  const hasPackageJson = await fileExists(join(projectRoot, 'package.json'));
+  const { command: testCommand } = resolveTestCommand({
+    manifest: tree.manifest, cliFlag: flags['test-cmd'], hasPackageJson,
+  });
+  const fbsAcIds = new Set(fbs.acIds ?? []);
+  const coveringTs = (tree.testSuites ?? []).filter((ts) => (ts.acIds ?? []).some((a) => fbsAcIds.has(a)));
+  const runnerInput = {
+    fbsId, acIds: fbs.acIds ?? [], testSuites: coveringTs,
+    sizing: defaultSizing(), testCommand: testCommand ?? undefined, projectRoot,
+  };
+  let mutationSampling;
+  try {
+    const runnerOut = await mutationRunner(runnerInput);
+    mutationSampling = runnerOut?.record;
+  } catch (err) {
+    writeUnexpectedFailure(
+      rcfError({ kind: 'ioFailure', message: `review: mutation runner failed: ${err.message}`, stack: err.stack }),
+      stderr,
+    );
+    return 1;
+  }
+
+  const record = composeReviewAuditRecord({
+    tree, fbs, findings, mutationSampling,
+    now: deps.now ? new Date(deps.now()) : new Date(),
+  });
+
+  if (flags.json) stdout.write(`${JSON.stringify(record, null, 2)}\n`);
+
+  if (flags['dry-run']) {
+    if (!flags.quiet) {
+      stdout.write(`[dry-run] review ${fbsId}: ${findings.length} finding(s); verdict=${record.verdict}\n`);
+      for (const f of findings) {
+        stdout.write(`  [${f.severity}] ${f.kind} ${f.tsId}${f.tcId ? '/' + f.tcId : ''}: ${f.detail}\n`);
+      }
+    }
+    return record.verdict === 'pass' ? 0 : 4;
+  }
+
+  // Write the record to the manifest.
+  const nextManifest = { ...(tree.manifest ?? {}) };
+  const existing = Array.isArray(nextManifest.reviewAudit) ? nextManifest.reviewAudit : [];
+  nextManifest.reviewAudit = [...existing, record];
+  if (testCommand && nextManifest.testCommand !== testCommand && !nextManifest.testCommand) {
+    // Optionally record the resolved testCommand when not already set,
+    // so a later re-audit inherits the same resolution without a flag.
+    nextManifest.testCommand = testCommand;
+  }
+  const relPath = 'rcf/manifest.json';
+  const validation = validateDocument({ doc: nextManifest, kind: 'manifest', filePath: relPath });
+  if (validation) {
+    stderr.write(`[error] validation ${validation.message}\n`);
+    return 3;
+  }
+  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) {
+    writeUnexpectedFailure(
+      rcfError({ kind: 'ioFailure', message: `review: manifest write failed: ${err.message}`, filePath: relPath, stack: err.stack }),
+      stderr,
+    );
+    return 1;
+  }
+  if (!flags.quiet) {
+    stdout.write(`review ${fbsId}: wrote ${record.id} to rcf/manifest.json (${findings.length} findings, verdict=${record.verdict}).\n`);
+  }
+  return record.verdict === 'pass' ? 0 : 4;
+}
+
+async function fileExists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Default file lister used by the UI-baseline drift audit. Walks the
+ * project tree once and matches each path against the supplied glob
+ * patterns. Supports the `**` suffix (recursive) and `*` mid-path
+ * wildcards. Deliberately minimal: the audit's callers pass either
+ * `src/ui/**` or `src/routes/**` in v1, so a formal glob library
+ * would be scope-creep. Returns project-root-relative paths.
+ *
+ * @param {string} projectRoot
+ * @returns {(patterns: string[]) => Promise<string[]>}
+ */
+function defaultListFiles(projectRoot) {
+  return async (patterns) => {
+    const out = new Set();
+    for (const raw of Array.isArray(patterns) ? patterns : []) {
+      const pattern = String(raw);
+      const idx = pattern.indexOf('**');
+      let root;
+      let recursive;
+      let suffix;
+      if (idx >= 0) {
+        root = pattern.slice(0, Math.max(0, idx - 1));
+        recursive = true;
+        suffix = pattern.slice(idx + 2).replace(/^\//, '');
+      } else if (pattern.includes('*')) {
+        const slash = pattern.lastIndexOf('/');
+        root = slash >= 0 ? pattern.slice(0, slash) : '.';
+        recursive = false;
+        suffix = pattern.slice(slash + 1);
+      } else {
+        // Literal path; include as-is.
+        root = pattern;
+        recursive = false;
+        suffix = '';
+      }
+      const absRoot = join(projectRoot, root);
+      const collected = [];
+      await walkDir(absRoot, recursive, collected);
+      for (const abs of collected) {
+        const rel = relative(projectRoot, abs);
+        if (matchesSuffix(rel, suffix)) out.add(rel);
+      }
+    }
+    return [...out];
+  };
+}
+
+async function walkDir(root, recursive, out) {
+  let entries;
+  try { entries = await readdir(root, { withFileTypes: true }); } catch { return; }
+  for (const entry of entries) {
+    const abs = join(root, entry.name);
+    if (entry.isDirectory()) {
+      if (recursive) await walkDir(abs, true, out);
+    } else if (entry.isFile()) {
+      out.push(abs);
+    }
+  }
+}
+
+function matchesSuffix(rel, suffix) {
+  if (!suffix || suffix.length === 0) return true;
+  // Support a single `*` wildcard on the suffix segment.
+  const escaped = suffix.split('*').map((p) => p.replace(/[.+?^${}()|[\]\\]/g, '\\$&')).join('.*');
+  return new RegExp(`(?:^|/)${escaped}$`).test(rel);
+}