rcf-lite 0.0.1 → 0.7.1

package/src/review/index.js

@@ -0,0 +1,325 @@
+// REVIEW-stage test-theatre audit + mutation-sampling
+// (verification-integrity-cluster-spec §5.5, §6).
+//
+// Two surfaces composed into ONE Review pass, emitting ONE
+// reviewAudit record per FBS:
+//
+//   1. test-theatre audit (deterministic): five finding categories from
+//      §5.5 - mockOnlyIntegrationClaim, testPointerBroken,
+//      assertionStrengthWeak, acIdsCoverageDrift, otherDeclared. This
+//      module implements the four deterministic ones; assertion strength
+//      needs a code-reading agent, so v1 raises it only via the
+//      mutation-sampling side, not the deterministic sweep (the sweep is
+//      the belt, the mutation-sampling agent is the braces).
+//
+//   2. mutation-sampling (agent-driven, injectable): the runner accepts
+//      a `mutationRunner` dependency conforming to the spec §6 shape.
+//      The runner takes the FBS diff and TS/TC list and returns the
+//      mutation-sampling record. When no runner is wired, the audit
+//      emits a `notes` entry explaining that the sampler was not run;
+//      the reviewAudit record is still valid schema.
+
+import { classifyAttestationProfile, aggregateAttestationsByAc } from '../query/attestation.js';
+
+/**
+ * @typedef {import('#core/store/walker.js').TreeModel} TreeModel
+ * @typedef {'mockOnlyIntegrationClaim'|'testPointerBroken'|'assertionStrengthWeak'|'acIdsCoverageDrift'|'uiBaselineDrift'|'otherDeclared'} TestTheatreFindingKind
+ */
+
+/**
+ * @typedef {object} TestTheatreFinding
+ * @property {string} [tsId] required for test-theatre kinds; omitted on kind=uiBaselineDrift (rcf-schemas 0.4.2)
+ * @property {string} [tcId]
+ * @property {string} [anchorId] free-form anchor for kinds without a test suite (for example, uiBaselineDrift, anchored on an FBS id or file path)
+ * @property {TestTheatreFindingKind} kind
+ * @property {string} detail
+ * @property {'advisory'|'warn'|'block'} severity
+ * @property {string} [kindDescription]
+ */
+
+/**
+ * @typedef {object} MutationSurvivor
+ * @property {string} mutationId
+ * @property {string} targetFile
+ * @property {string} [targetSymbol]
+ * @property {string} mutationSummary
+ * @property {string[]} acIds
+ * @property {string[]} [tsIdsShouldHaveCaught]
+ * @property {string[]} [tcIdsShouldHaveCaught]
+ */
+
+/**
+ * @typedef {object} MutationSamplingRecord
+ * @property {string} mode
+ * @property {number} mutantsGenerated
+ * @property {number} mutantsRun
+ * @property {number} killed
+ * @property {number} survived
+ * @property {number} [durationMs]
+ * @property {MutationSurvivor[]} [survivors]
+ * @property {string} [notes]
+ */
+
+const INTEGRATION_LEVELS = new Set(['integration', 'e2e', 'contract']);
+const MOCK_PROFILES = new Set(['mock', 'stub', 'fixture']);
+
+/**
+ * Detect `mockOnlyIntegrationClaim`: a TS whose testLevel is
+ * integration-or-higher and every TC records `runtimeProvenance.profile`
+ * in {mock, stub, fixture} AND at least one bound AC's aggregated
+ * attestation is live or sandboxed. This is the exact d-142 failure
+ * mode.
+ *
+ * @param {TreeModel} tree
+ * @param {object} fbs
+ * @returns {TestTheatreFinding[]}
+ */
+function detectMockOnlyIntegrationClaim(tree, fbs) {
+  const findings = [];
+  const attByAc = aggregateAttestationsByAc(tree);
+  const fbsAcIds = new Set(fbs.acIds ?? []);
+  // Every TS that covers one of the FBS's ACs.
+  const relevantTs = (tree.testSuites ?? []).filter((ts) => (ts.acIds ?? []).some((a) => fbsAcIds.has(a)));
+  for (const ts of relevantTs) {
+    if (!INTEGRATION_LEVELS.has(ts.testLevel)) continue;
+    const tcs = ts.testCases ?? [];
+    if (tcs.length === 0) continue;
+    const allMockShaped = tcs.every((tc) => MOCK_PROFILES.has(tc?.runtimeProvenance?.profile ?? ''));
+    if (!allMockShaped) continue;
+    const bindingsOnFbsAcs = (ts.acIds ?? [])
+      .filter((a) => fbsAcIds.has(a))
+      .flatMap((a) => attByAc.get(a) ?? []);
+    const liveish = bindingsOnFbsAcs.find((b) => b.attestationMode === 'live' || b.attestationMode === 'sandboxed');
+    if (liveish) {
+      findings.push({
+        tsId: ts.id,
+        kind: 'mockOnlyIntegrationClaim',
+        detail: `${ts.id} testLevel=${ts.testLevel} but every TC's runtimeProvenance.profile is in {mock,stub,fixture}, while AC bindings include service ${liveish.serviceId} attested ${liveish.attestationMode}.`,
+        severity: 'block',
+      });
+    }
+  }
+  return findings;
+}
+
+/**
+ * Detect `testPointerBroken`: any TC whose `testPointer` is missing or
+ * fails resolution. Uses the pre-computed testPointers map (a resolved
+ * pointer's `.resolved === true`). When no map is supplied, we skip
+ * this check (the caller must pass one for the audit to police it).
+ *
+ * @param {TreeModel} tree
+ * @param {object} fbs
+ * @param {Map<string, { resolved?: boolean, testPointer?: string|null, reason?: string }>} [testPointers]
+ * @returns {TestTheatreFinding[]}
+ */
+function detectTestPointerBroken(tree, fbs, testPointers) {
+  if (!testPointers || testPointers.size === 0) return [];
+  const findings = [];
+  const fbsAcIds = new Set(fbs.acIds ?? []);
+  for (const ts of tree.testSuites ?? []) {
+    for (const tc of ts.testCases ?? []) {
+      if (!fbsAcIds.has(tc.acId)) continue;
+      const key = `${ts.id}::${tc.id}`;
+      const resolution = testPointers.get(key);
+      if (!resolution || resolution.resolved !== true) {
+        findings.push({
+          tsId: ts.id,
+          tcId: tc.id,
+          kind: 'testPointerBroken',
+          detail: `TC ${tc.id} testPointer '${resolution?.testPointer ?? tc.testPointer ?? '(missing)'}' does not resolve: ${resolution?.reason ?? 'missing-pointer'}.`,
+          severity: 'block',
+        });
+      }
+    }
+  }
+  return findings;
+}
+
+/**
+ * Detect `acIdsCoverageDrift`: an FBS acId that no TS covers, OR a
+ * covering TS acId that this FBS does not claim.
+ *
+ * @param {TreeModel} tree
+ * @param {object} fbs
+ * @returns {TestTheatreFinding[]}
+ */
+function detectAcIdsCoverageDrift(tree, fbs) {
+  const findings = [];
+  const fbsAcIds = new Set(fbs.acIds ?? []);
+  for (const ts of tree.testSuites ?? []) {
+    const covers = (ts.acIds ?? []).some((a) => fbsAcIds.has(a));
+    if (!covers) continue;
+    for (const a of ts.acIds ?? []) {
+      if (!fbsAcIds.has(a)) {
+        findings.push({
+          tsId: ts.id,
+          kind: 'acIdsCoverageDrift',
+          detail: `${ts.id} covers ${a}, but ${fbs.fbsId} does not claim ${a} in acIds[].`,
+          severity: 'warn',
+        });
+      }
+    }
+  }
+  // The reverse ("FBS claims an AC no TS covers") is intentionally
+  // deferred to `coverage --strict`, which already raises exit 4 on
+  // uncovered ACs and needs no tsId to do so (the reviewAudit schema
+  // requires a valid tsId on every testTheatreFinding, and the "no TS
+  // covers" case has none to name). Belt and braces: coverage is the
+  // belt, this audit is the braces.
+  return findings;
+}
+
+/**
+ * Detect `attestationDrift` findings as test-theatre entries. This is
+ * the passWithWarn class from §3.5 (declaredMockOnly × live) plus the
+ * refuse class (already blocking coverage --strict, but re-raised here
+ * so the Review record surfaces it too).
+ *
+ * The kind used is `mockOnlyIntegrationClaim` when the drift refuses
+ * live-attested ACs on mock-profile TCs; the standalone `attestationDrift`
+ * kind is not in the schema enum (spec §3.4 fixed enum), so v1 folds
+ * these into the closest matching kind (`mockOnlyIntegrationClaim` for
+ * live-attested drift, `otherDeclared` with a kindDescription for the
+ * passWithWarn drift). This is spec-faithful — §5.5 defines only the
+ * enumerated `kind` set, and downstream consumers key on that set.
+ *
+ * @param {TreeModel} tree
+ * @param {object} fbs
+ * @returns {TestTheatreFinding[]}
+ */
+function detectAttestationDrift(tree, fbs) {
+  const findings = [];
+  const attByAc = aggregateAttestationsByAc(tree);
+  const fbsAcIds = new Set(fbs.acIds ?? []);
+  for (const ts of tree.testSuites ?? []) {
+    for (const tc of ts.testCases ?? []) {
+      if (!fbsAcIds.has(tc.acId)) continue;
+      const profile = tc?.runtimeProvenance?.profile;
+      if (typeof profile !== 'string') continue;
+      const bindings = attByAc.get(tc.acId) ?? [];
+      for (const { serviceId, attestationMode } of bindings) {
+        const cell = classifyAttestationProfile(attestationMode, profile);
+        if (cell.verdict === 'passWithWarn') {
+          findings.push({
+            tsId: ts.id,
+            tcId: tc.id,
+            kind: 'otherDeclared',
+            kindDescription: 'attestationDrift',
+            detail: `${ts.id}/${tc.id} on ${tc.acId} (service ${serviceId}): ${cell.reason}`,
+            severity: 'warn',
+          });
+        }
+      }
+    }
+  }
+  return findings;
+}
+
+/**
+ * Run the deterministic test-theatre audit on one FBS. Returns the
+ * findings list (aggregated across the four detectors).
+ *
+ * @param {object} args
+ * @param {TreeModel} args.tree
+ * @param {object} args.fbs
+ * @param {Map<string, object>} [args.testPointers]
+ * @returns {TestTheatreFinding[]}
+ */
+export function auditTestTheatre({ tree, fbs, testPointers }) {
+  return [
+    ...detectMockOnlyIntegrationClaim(tree, fbs),
+    ...detectTestPointerBroken(tree, fbs, testPointers),
+    ...detectAcIdsCoverageDrift(tree, fbs),
+    ...detectAttestationDrift(tree, fbs),
+  ];
+}
+
+/**
+ * @typedef {object} ReviewAuditRecord
+ * @property {string} id                           `ra-<fbsId>-<n>`
+ * @property {string} fbsId
+ * @property {string} createdAt
+ * @property {TestTheatreFinding[]} testTheatreFindings
+ * @property {MutationSamplingRecord} [mutationSampling]
+ * @property {'pass'|'warn'|'block'} verdict
+ */
+
+/**
+ * Aggregate a verdict from the findings + mutation sampling per spec
+ * §5.5: block if any finding severity is block or any mutation
+ * survivor traces to an in-scope AC; warn if any warn and no block;
+ * pass otherwise.
+ *
+ * Review N-2 (non-blocking): an unwired mutation runner
+ * (`mode: 'agent-v1-not-wired'`) is promoted to `warn` even on an
+ * otherwise-clean audit. Without this, an unwired runner is
+ * indistinguishable from a wired runner that killed every mutant:
+ * both emit `verdict: pass`, so the exit-code layer conflates "audit
+ * clean" with "audit did not run". Warn forces the operator to wire a
+ * runner or pass `--skip-mutation` (mode: 'skipped'), which remains
+ * pass as an explicit operator choice.
+ *
+ * @param {TestTheatreFinding[]} findings
+ * @param {MutationSamplingRecord} [mutationSampling]
+ * @returns {'pass'|'warn'|'block'}
+ */
+export function aggregateVerdict(findings, mutationSampling) {
+  const severities = findings.map((f) => f.severity);
+  if (severities.includes('block')) return 'block';
+  if ((mutationSampling?.survivors?.length ?? 0) > 0) return 'block';
+  if (severities.includes('warn')) return 'warn';
+  if (mutationSampling?.mode === 'agent-v1-not-wired') return 'warn';
+  return 'pass';
+}
+
+/**
+ * Monotonic id allocator for the reviewAudit array.
+ *
+ * @param {object|null} manifest
+ * @param {string} fbsId
+ * @returns {string}
+ */
+export function nextReviewAuditId(manifest, fbsId) {
+  const prefix = `ra-${fbsId}-`;
+  const existing = Array.isArray(manifest?.reviewAudit) ? manifest.reviewAudit : [];
+  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 record. Timestamps at UTC ISO.
+ *
+ * @param {object} args
+ * @param {TreeModel} args.tree
+ * @param {object} args.fbs
+ * @param {TestTheatreFinding[]} args.findings
+ * @param {MutationSamplingRecord} [args.mutationSampling]
+ * @param {Date} [args.now]
+ * @returns {ReviewAuditRecord}
+ */
+export function composeReviewAuditRecord({ tree, fbs, findings, mutationSampling, now = new Date() }) {
+  const id = nextReviewAuditId(tree.manifest, fbs.fbsId);
+  const verdict = aggregateVerdict(findings, mutationSampling);
+  const record = {
+    id,
+    fbsId: fbs.fbsId,
+    createdAt: now.toISOString(),
+    testTheatreFindings: findings.map((f) => normaliseFinding(f)),
+    verdict,
+  };
+  if (mutationSampling) record.mutationSampling = mutationSampling;
+  return record;
+}
+
+function normaliseFinding(f) {
+  const out = { tsId: f.tsId, kind: f.kind, detail: f.detail, severity: f.severity };
+  if (typeof f.tcId === 'string' && f.tcId.length > 0) out.tcId = f.tcId;
+  if (typeof f.kindDescription === 'string' && f.kindDescription.length > 0) out.kindDescription = f.kindDescription;
+  return out;
+}

package/src/review/mutation.js

@@ -0,0 +1,117 @@
+// Agent-driven mutation-sampling coordinator
+// (verification-integrity-cluster-spec §6).
+//
+// This module owns the ORCHESTRATION contract, not the agent dispatch.
+// The actual mutation-sampling is done by a Review-stage subagent (§6.5,
+// §6.6) that runs in a worktree, applies each mutation, runs the test
+// command, and records kill / survive. The subagent lives outside the
+// build package (it is a Claude Code dispatch orchestrated by the
+// harness, spec §6.7 note that native tool adapters are v2). Build
+// provides:
+//   - the CONTRACT the runner must satisfy (function shape, input, output);
+//   - a DEFAULT runner that no-ops with a clear note when no wiring is
+//     supplied (the record still validates against the schema); this
+//     lets `rcf review` return a valid reviewAudit record on any repo,
+//     even before the harness is set up;
+//   - the SIZING policy (§6.3) and TEST-COMMAND resolver (§6.4).
+//
+// The wire-up: `rcf review` accepts `--mutation-runner <name>` (in a
+// future iteration) or a dep-injected runner (this iteration). In tests,
+// injection is direct. In production, the harness passes a runner that
+// dispatches an Opus 4.7 subagent per the estate ladder.
+
+/**
+ * @typedef {object} MutationRunnerInput
+ * @property {string} fbsId
+ * @property {string[]} acIds                 the FBS's in-scope ACs
+ * @property {object[]} testSuites            the TSes that cover any of the ACs
+ * @property {object} sizing                  min/max/timeBudgetMs
+ * @property {string} [testCommand]           resolved test command (§6.4)
+ * @property {string} projectRoot
+ */
+
+/**
+ * @typedef {object} MutationRunnerOutput
+ * @property {import('./index.js').MutationSamplingRecord} record
+ */
+
+/**
+ * @typedef {(input: MutationRunnerInput) => Promise<MutationRunnerOutput>} MutationRunner
+ */
+
+/**
+ * Resolve the sizing policy for a mutation-sampling pass. Spec §6.3:
+ * 10 min, 30 max, ~3 mutants per 50 LOC of changed function bodies,
+ * default 10-minute time budget. LOC counting is the runner's job;
+ * this returns the plain envelope.
+ *
+ * @param {object} [opts]
+ * @param {number} [opts.timeBudgetMs]
+ * @returns {{ min: number, max: number, timeBudgetMs: number }}
+ */
+export function defaultSizing({ timeBudgetMs = 10 * 60 * 1000 } = {}) {
+  return { min: 10, max: 30, timeBudgetMs };
+}
+
+/**
+ * Test command resolution (§6.4): manifest.testCommand -> flag ->
+ * fallback. Returns the resolved command string OR the reason a
+ * fallback was reached. Never throws — the caller records the reason
+ * on the mutation-sampling record when applicable.
+ *
+ * @param {object} args
+ * @param {object|null} args.manifest
+ * @param {string} [args.cliFlag]
+ * @param {boolean} args.hasPackageJson
+ * @returns {{ command: string|null, source: 'manifest'|'flag'|'fallback'|'unresolved' }}
+ */
+export function resolveTestCommand({ manifest, cliFlag, hasPackageJson }) {
+  if (typeof cliFlag === 'string' && cliFlag.length > 0) {
+    return { command: cliFlag, source: 'flag' };
+  }
+  if (typeof manifest?.testCommand === 'string' && manifest.testCommand.length > 0) {
+    return { command: manifest.testCommand, source: 'manifest' };
+  }
+  if (hasPackageJson) return { command: 'npm test', source: 'fallback' };
+  return { command: null, source: 'unresolved' };
+}
+
+/**
+ * Default runner: emits a valid mutation-sampling record with zero
+ * mutants and a `notes` explaining that no runner was wired. This is
+ * the "no-op with honesty" path — the reviewAudit record stays valid,
+ * the audit's verdict is not spoofed, and the operator sees an
+ * explicit message rather than a silent green.
+ *
+ * @type {MutationRunner}
+ */
+export async function defaultMutationRunner() {
+  return {
+    record: {
+      mode: 'agent-v1-not-wired',
+      mutantsGenerated: 0,
+      mutantsRun: 0,
+      killed: 0,
+      survived: 0,
+      notes: 'No mutation-sampling runner supplied. Wire one via the harness (spec §6.5-§6.7) or run --skip-mutation to acknowledge the omission on the record.',
+    },
+  };
+}
+
+/**
+ * Explicit skip: same shape as the default runner but says so.
+ *
+ * @type {MutationRunner}
+ */
+export async function skippedMutationRunner() {
+  return {
+    record: {
+      mode: 'skipped',
+      mutantsGenerated: 0,
+      mutantsRun: 0,
+      killed: 0,
+      survived: 0,
+      notes: 'Mutation sampling skipped by --skip-mutation.',
+    },
+  };
+}

package/src/review/ui-baseline-drift.js

@@ -0,0 +1,138 @@
+// Stage-3 UI baseline drift audit
+// (ui-design-gate-0.7.0-spec §3.4, §7 mandate 1, mandate 3).
+//
+// Runs alongside the existing Track A test-theatre audit and emits
+// findings on the same reviewAudit record under the `uiBaselineDrift`
+// kind (schema-registered on `reviewAudit.testTheatreFindings[].kind`
+// per rcf-schemas@0.4.0).
+//
+// Two deterministic checks in v1:
+//   1. `noHexInViewFiles` (§7 mandate 1): any view file matches
+//      /#[0-9a-fA-F]{3,8}\b/ while the baseline sets
+//      `defaults.noHexInViewFiles: true`. Severity: block. Scope is
+//      configurable via `uiBaseline.defaults.viewFileGlobs` (default
+//      ["src/ui/**"], minus the themeTokensModule path).
+//   2. `sharedLayoutImport` (§7 mandate 3): route files (default heuristic
+//      src/routes/**) do NOT import the sharedLayoutModule declared on
+//      the baseline. Severity: block.
+//
+// Both checks are opt-out-aware via `uiBaseline.operatorOptOuts[]`; the
+// finding is still recorded (so the operator can see the drift), but
+// severity demotes to `advisory` when the opt-out matches.
+//
+// The audit is a pure function of (fbs, uiBaseline, file listing +
+// contents). Callers supply the file listing so tests can stub without
+// touching disk.
+
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+/**
+ * @typedef {import('./index.js').TestTheatreFinding} TestTheatreFinding
+ */
+
+const HEX_RE = /#[0-9a-fA-F]{3,8}\b/;
+
+/**
+ * Run the UI-baseline drift audit on one FBS. Requires `uiBaseline`
+ * present on the manifest; when absent, returns an empty list (the
+ * baseline is the ruling, and no baseline means nothing to drift from
+ * for this audit - coverage of that state lives elsewhere).
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @param {object} args.fbs
+ * @param {object|null} args.uiBaseline
+ * @param {(patterns: string[]) => Promise<string[]>} args.listFiles  glob helper (injectable; project-root-relative paths returned)
+ * @returns {Promise<TestTheatreFinding[]>}
+ */
+export async function auditUiBaselineDrift({ projectRoot, fbs, uiBaseline, listFiles }) {
+  /** @type {TestTheatreFinding[]} */
+  const findings = [];
+  if (!uiBaseline || fbs?.uiBearing !== true) return findings;
+
+  const defaults = uiBaseline.defaults ?? {};
+  const optOuts = new Set((uiBaseline.operatorOptOuts ?? []).map((o) => o.field));
+
+  // 1. noHexInViewFiles
+  if (defaults.noHexInViewFiles === true) {
+    const globs = Array.isArray(defaults.viewFileGlobs) && defaults.viewFileGlobs.length > 0
+      ? defaults.viewFileGlobs
+      : ['src/ui/**'];
+    const tokensModule = typeof defaults.designTokensModule === 'string' ? defaults.designTokensModule : null;
+    const files = await safeListFiles(listFiles, globs);
+    for (const rel of files) {
+      if (tokensModule && rel === tokensModule) continue;
+      const abs = join(projectRoot, rel);
+      let contents;
+      try { contents = await readFile(abs, 'utf8'); } catch { continue; }
+      const match = HEX_RE.exec(contents);
+      if (match) {
+        const severity = optOuts.has('noHexInViewFiles') ? 'advisory' : 'block';
+        findings.push({
+          // Track B review N-5 (@stravica-ai/rcf-schemas 0.4.2): the
+          // finding anchors on the FBS id via the dedicated anchorId
+          // field. Prior versions smuggled fbs.fbsId through the tsId
+          // slot to satisfy the pre-0.4.2 blanket required rule; the
+          // slot mismatch was a real category-vs-slot defect (a
+          // downstream reader assuming tsId names a TS would follow a
+          // broken pointer). 0.4.2 keeps tsId required for the
+          // test-theatre kinds only.
+          anchorId: fbs.fbsId,
+          kind: 'uiBaselineDrift',
+          detail: `hex literal ${match[0]} detected in ${rel} (baseline defaults.noHexInViewFiles: true). Move colours into ${tokensModule ?? 'the design tokens module'}.`,
+          severity,
+        });
+      }
+    }
+  }
+
+  // 2. sharedLayoutImport
+  if (typeof defaults.sharedLayoutModule === 'string' && defaults.sharedLayoutModule.length > 0) {
+    const routeGlobs = Array.isArray(defaults.routeFileGlobs) && defaults.routeFileGlobs.length > 0
+      ? defaults.routeFileGlobs
+      : ['src/routes/**'];
+    const layoutModule = defaults.sharedLayoutModule;
+    const layoutBase = basename(layoutModule).replace(/\.[jt]sx?$/, '');
+    const files = await safeListFiles(listFiles, routeGlobs);
+    for (const rel of files) {
+      const abs = join(projectRoot, rel);
+      let contents;
+      try { contents = await readFile(abs, 'utf8'); } catch { continue; }
+      // A route file is expected to import the shared layout module,
+      // either by the module path or by the module basename. Both are
+      // recognised; the check is a coarse heuristic, not a formal AST.
+      const hasImport = contents.includes(layoutModule)
+        || new RegExp(`\\b${escapeForRegExp(layoutBase)}\\b`).test(contents);
+      if (!hasImport) {
+        const severity = optOuts.has('sharedLayoutModule') ? 'advisory' : 'block';
+        findings.push({
+          // See the noHexInViewFiles comment above for the anchorId
+          // rationale (rcf-schemas 0.4.2, Track B review N-5).
+          anchorId: fbs.fbsId,
+          kind: 'uiBaselineDrift',
+          detail: `${rel} does not import the shared layout module (${layoutModule}); baseline mandate 3 says every route uses one layout.`,
+          severity,
+        });
+      }
+    }
+  }
+  return findings;
+}
+
+async function safeListFiles(listFiles, patterns) {
+  if (typeof listFiles !== 'function') return [];
+  try {
+    const raw = await listFiles(patterns);
+    return Array.isArray(raw) ? raw : [];
+  } catch { return []; }
+}
+
+function basename(path) {
+  const idx = String(path).lastIndexOf('/');
+  return idx >= 0 ? String(path).slice(idx + 1) : String(path);
+}
+
+function escapeForRegExp(s) {
+  return String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}