rcf-lite 0.20.0 → 0.21.0

package/src/browser-verify/pack-browser.js

@@ -0,0 +1,294 @@
+// packBrowser: a real headless browser exposed to blueprint-shipped
+// probe packs (visual-round-spec-2026-09-04 §3.3). The browser is
+// provisioned through the pinned Playwright MCP server as a JSON-RPC
+// 2.0 stdio client, with an optional cheaper route via a `playwright`
+// installation already resolved from the consuming project's own
+// node_modules. Both routes expose the same small stable API:
+//
+//   goto(url)                  navigate to a URL
+//   snapshot()                 accessibility-tree text (searchable)
+//   evaluate(fn, arg?)         run JS in page context; returns parsed value
+//   click(selectorOrRef, hint) click an element by CSS selector or a11y ref
+//   type(selectorOrRef, text)  type into an editable element
+//   press(key)                 press a keyboard key
+//   resize(width, height)      set viewport dimensions (breakpoint reflow probes)
+//   screenshot(filename?)      capture a PNG; returns descriptor / path
+//   close()                    close the page + terminate the browser process
+//
+// Zero new npm dependencies: MCP over stdio uses only Node built-ins;
+// the cheap route uses `playwright` peer dep if the project already
+// installed it. No LLM call anywhere.
+
+import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+import { resolve as resolvePath } from 'node:path';
+
+import { PLAYWRIGHT_MCP_VERSION } from '../verify/engine/launcher.js';
+
+const DEFAULT_TOOL_TIMEOUT_MS = 30000;
+const INIT_TIMEOUT_MS = 45000;
+
+/**
+ * Compose a packBrowser for use by probe packs.
+ *
+ * @param {object} [options]
+ * @param {string} [options.projectRoot]           consuming project root; used to try the cheap route
+ * @param {string} [options.playwrightMcpVersion]  pinned MCP semver (defaults to PLAYWRIGHT_MCP_VERSION)
+ * @param {'auto'|'mcp'|'project'} [options.route] force a route (default 'auto')
+ * @param {(line: string) => void} [options.logger]
+ * @param {NodeJS.ProcessEnv} [options.env]
+ * @param {number} [options.timeoutMs]             per-RPC timeout
+ * @returns {Promise<object>}                      the packBrowser handle
+ */
+export async function createPackBrowser(options = {}) {
+  const {
+    projectRoot,
+    playwrightMcpVersion = PLAYWRIGHT_MCP_VERSION,
+    route = 'auto',
+    logger = () => {},
+    env = process.env,
+    timeoutMs = DEFAULT_TOOL_TIMEOUT_MS,
+  } = options;
+
+  if (route === 'project' || (route === 'auto' && projectRoot && await tryResolveProjectPlaywright(projectRoot))) {
+    const handle = await createProjectPlaywrightHandle({ projectRoot, logger });
+    if (handle) return handle;
+    if (route === 'project') throw new Error(`packBrowser: project route requested but 'playwright' is not installed under ${projectRoot}`);
+  }
+  return createMcpPackBrowser({ playwrightMcpVersion, logger, env, timeoutMs });
+}
+
+async function tryResolveProjectPlaywright(projectRoot) {
+  try {
+    const req = createRequire(resolvePath(projectRoot, 'package.json'));
+    req.resolve('playwright');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function createProjectPlaywrightHandle({ projectRoot, logger }) {
+  try {
+    const req = createRequire(resolvePath(projectRoot, 'package.json'));
+    const playwrightPath = req.resolve('playwright');
+    const mod = await import(pathToFileURL(playwrightPath).href);
+    const chromium = mod?.chromium ?? mod?.default?.chromium;
+    if (!chromium) return null;
+    const browser = await chromium.launch({ headless: true });
+    const context = await browser.newContext();
+    const page = await context.newPage();
+    return Object.freeze({
+      provisioning: { via: 'project-playwright', playwrightPath },
+      async goto(url) { await page.goto(url, { waitUntil: 'load' }); },
+      async snapshot() {
+        const tree = await page.accessibility.snapshot({ interestingOnly: false });
+        return renderA11yTree(tree);
+      },
+      async evaluate(fn, arg) {
+        if (typeof fn === 'function') return page.evaluate(fn, arg);
+        return page.evaluate(String(fn));
+      },
+      async click(selector) { await page.click(selector); },
+      async type(selector, text) { await page.fill(selector, text); },
+      async press(key) { await page.keyboard.press(key); },
+      async resize(width, height) {
+        const w = normaliseDim(width, 'width');
+        const h = normaliseDim(height, 'height');
+        await page.setViewportSize({ width: w, height: h });
+      },
+      async screenshot(filename) {
+        const target = filename ? { path: filename } : undefined;
+        const buf = await page.screenshot(target);
+        return filename ?? `data:image/png;base64,${buf.toString('base64')}`;
+      },
+      async close() {
+        logger('[pack-browser] closing project-playwright browser');
+        try { await page.close(); } catch { /* fine */ }
+        try { await context.close(); } catch { /* fine */ }
+        try { await browser.close(); } catch { /* fine */ }
+      },
+    });
+  } catch (err) {
+    logger(`[pack-browser] project-playwright route failed: ${err.message}`);
+    return null;
+  }
+}
+
+function renderA11yTree(node, depth = 0) {
+  if (!node) return '';
+  const pad = '  '.repeat(depth);
+  const parts = [];
+  parts.push(`${pad}${node.role ?? '?'} ${node.name ? JSON.stringify(node.name) : ''}`.trimEnd());
+  for (const child of node.children ?? []) parts.push(renderA11yTree(child, depth + 1));
+  return parts.join('\n');
+}
+
+async function createMcpPackBrowser({ playwrightMcpVersion, logger, env, timeoutMs }) {
+  const child = spawn('npx', ['-y', `@playwright/mcp@${playwrightMcpVersion}`, '--headless', '--isolated'], {
+    env: { ...env },
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+
+  /** @type {Map<number, { resolve: (v: any) => void, reject: (e: Error) => void, timer: NodeJS.Timeout|null }>} */
+  const pending = new Map();
+  let nextId = 1;
+  let buffer = '';
+  let exited = false;
+
+  child.stdout.on('data', (chunk) => {
+    buffer += chunk.toString('utf8');
+    for (;;) {
+      const nl = buffer.indexOf('\n');
+      if (nl === -1) break;
+      const line = buffer.slice(0, nl).trim();
+      buffer = buffer.slice(nl + 1);
+      if (!line) continue;
+      let msg;
+      try { msg = JSON.parse(line); } catch { continue; }
+      if (msg.id != null && pending.has(msg.id)) {
+        const p = pending.get(msg.id);
+        pending.delete(msg.id);
+        if (p.timer) clearTimeout(p.timer);
+        if (msg.error) p.reject(new Error(msg.error.message ?? `MCP error ${JSON.stringify(msg.error)}`));
+        else p.resolve(msg.result);
+      }
+    }
+  });
+  child.stderr.on('data', (chunk) => logger(`[playwright-mcp] ${chunk.toString('utf8').trimEnd()}`));
+  child.on('exit', (code) => {
+    exited = true;
+    for (const [, p] of pending) {
+      if (p.timer) clearTimeout(p.timer);
+      p.reject(new Error(`Playwright MCP exited (code=${code})`));
+    }
+    pending.clear();
+  });
+
+  function rpc(method, params, { timeout = timeoutMs } = {}) {
+    if (exited) return Promise.reject(new Error('Playwright MCP process already exited'));
+    const id = nextId++;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        if (pending.has(id)) {
+          pending.delete(id);
+          reject(new Error(`MCP method ${method} timed out after ${timeout}ms`));
+        }
+      }, timeout);
+      pending.set(id, { resolve, reject, timer });
+      child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', id, method, params })}\n`);
+    });
+  }
+
+  async function tool(name, args) {
+    const result = await rpc('tools/call', { name, arguments: args ?? {} });
+    if (result?.isError) {
+      const text = textOf(result);
+      throw new Error(`Playwright MCP ${name} failed: ${text || JSON.stringify(result)}`);
+    }
+    return result;
+  }
+
+  await rpc('initialize', {
+    protocolVersion: '2024-11-05',
+    capabilities: {},
+    clientInfo: { name: 'rcf-lite-pack-browser', version: '0.0.0' },
+  }, { timeout: INIT_TIMEOUT_MS });
+  // Best-effort initialized notification (some servers ignore, that is fine).
+  try {
+    child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' })}\n`);
+  } catch { /* fine */ }
+
+  return Object.freeze({
+    provisioning: { via: 'playwright-mcp', version: playwrightMcpVersion },
+    async goto(url) {
+      await tool('browser_navigate', { url });
+    },
+    async snapshot() {
+      return textOf(await tool('browser_snapshot', {}));
+    },
+    async evaluate(fn, arg) {
+      const src = composeEvaluateSource(fn, arg);
+      const text = textOf(await tool('browser_evaluate', { function: src }));
+      return parseEvaluateResult(text);
+    },
+    async click(selector, hint) {
+      await tool('browser_click', { target: selector, element: hint ?? selector });
+    },
+    async type(selector, text, hint) {
+      await tool('browser_type', { target: selector, text, element: hint ?? selector });
+    },
+    async press(key) {
+      await tool('browser_press_key', { key });
+    },
+    async resize(width, height) {
+      const w = normaliseDim(width, 'width');
+      const h = normaliseDim(height, 'height');
+      await tool('browser_resize', { width: w, height: h });
+    },
+    async screenshot(filename) {
+      const args = filename ? { filename } : {};
+      return textOf(await tool('browser_take_screenshot', args));
+    },
+    async close() {
+      logger('[pack-browser] closing playwright-mcp browser');
+      try { await tool('browser_close', {}); } catch { /* fine */ }
+      try { child.stdin.end(); } catch { /* fine */ }
+      await new Promise((resolve) => {
+        if (exited) return resolve();
+        const timer = setTimeout(() => { try { child.kill('SIGKILL'); } catch { /* fine */ } resolve(); }, 5000);
+        child.once('exit', () => { clearTimeout(timer); resolve(); });
+      });
+    },
+  });
+}
+
+/**
+ * Coerce a viewport dimension argument to a positive integer.
+ * Exposed for unit tests through resize() call sites.
+ */
+function normaliseDim(value, label) {
+  const n = Number(value);
+  if (!Number.isFinite(n) || n <= 0) {
+    throw new Error(`packBrowser.resize: ${label} must be a positive number (got ${JSON.stringify(value)})`);
+  }
+  return Math.round(n);
+}
+
+function textOf(result) {
+  const parts = Array.isArray(result?.content) ? result.content : [];
+  return parts.map((c) => (c?.type === 'text' ? (c.text ?? '') : '')).join('\n');
+}
+
+function composeEvaluateSource(fn, arg) {
+  if (typeof fn !== 'function') return String(fn);
+  if (arg === undefined) return fn.toString();
+  return `() => (${fn.toString()})(${JSON.stringify(arg)})`;
+}
+
+/**
+ * The MCP browser_evaluate response is a human-readable text block, usually of
+ * the shape "- Ran Playwright code:\n... - Result: <json-ish>". Parse the trailing
+ * value out of it and JSON-parse when possible. Exported for unit tests.
+ */
+export function parseEvaluateResult(text) {
+  if (typeof text !== 'string') return text;
+  // MCP 0.0.80+ returns "### Result\n<value>\n### Ran Playwright code\n```js..."
+  const headed = text.match(/###\s*Result\s*\n([\s\S]*?)(?=\n###\s|\n?$)/);
+  if (headed) {
+    const inner = headed[1].trim().replace(/^```(?:json)?\s*/i, '').replace(/```\s*$/i, '').trim();
+    try { return JSON.parse(inner); } catch { return inner; }
+  }
+  // Older MCP shape: "Result: <value>" trailing block.
+  const marker = text.lastIndexOf('Result:');
+  const tail = marker >= 0 ? text.slice(marker + 'Result:'.length).trim() : text.trim();
+  const stripped = tail.replace(/^```(?:json)?\s*/i, '').replace(/```\s*$/i, '').trim();
+  try { return JSON.parse(stripped); } catch { return stripped; }
+}
+
+/**
+ * Internals exposed to unit tests. Not part of the public seam a
+ * probe pack sees; do not import from a pack.
+ */
+export const PACK_BROWSER_INTERNALS = Object.freeze({ normaliseDim });

package/src/browser-verify/pack-loader.js

@@ -0,0 +1,176 @@
+// Pack loader for blueprint-shipped probe packs
+// (visual round T-0, US-1701 AC-1701-1 / 2 / 3). CN-107.
+//
+// Given a list of applied blueprints, discovers each blueprint's
+// probe packs under `<blueprintAbsPath>/probe-packs/*.pack.{js,mjs}`,
+// imports each module dynamically, validates against the pack schema
+// (`pack-schema.js`), and cross-checks every check id against the AC
+// ids the blueprint contributes via `blueprint.json:contributions[]`.
+//
+// The loader is pure with respect to the filesystem it reads: no
+// writes, no side effects on the imported modules. It returns an
+// aggregate result (`packs`, `warnings`, `errors`) so the CLI can
+// emit one refusal diagnostic per fault rather than stop at the first.
+
+import { readdir, readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, resolve, isAbsolute } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { validatePackModule } from './pack-schema.js';
+
+const PACK_FILENAME_RE = /\.pack\.(?:js|mjs)$/;
+
+/**
+ * Load and validate probe packs under a set of applied blueprints.
+ *
+ * @param {object} args
+ * @param {Array<{ slug: string, absPath: string }>} args.appliedBlueprints
+ *   List of blueprints on the applied shelf. `absPath` is the
+ *   directory containing the blueprint's `blueprint.json`.
+ * @param {string} [args.projectRoot]  reserved; unused today.
+ * @returns {Promise<{ packs: Array<LoadedPack>, warnings: Array<{ packAbsPath: string, message: string }>, errors: Array<{ packAbsPath: string, message: string }> }>}
+ */
+export async function loadProbePacks({ appliedBlueprints, projectRoot: _projectRoot }) {
+  const packs = [];
+  const warnings = [];
+  const errors = [];
+
+  for (const bp of Array.isArray(appliedBlueprints) ? appliedBlueprints : []) {
+    if (!bp || typeof bp.slug !== 'string' || typeof bp.absPath !== 'string' || !isAbsolute(bp.absPath)) {
+      errors.push({
+        packAbsPath: '(no path)',
+        message: `pack-loader: blueprint entry must carry { slug: string, absPath: absolute path } (got ${JSON.stringify(bp)})`,
+      });
+      continue;
+    }
+    const packsDir = join(bp.absPath, 'probe-packs');
+    if (!existsSync(packsDir)) continue;
+
+    let contributedAcIds;
+    try {
+      contributedAcIds = await readContributedAcIds({ blueprintAbsPath: bp.absPath });
+    } catch (err) {
+      errors.push({ packAbsPath: bp.absPath, message: `pack-loader: cannot read blueprint contributions for '${bp.slug}': ${err.message}` });
+      continue;
+    }
+
+    let entries;
+    try {
+      entries = await readdir(packsDir, { withFileTypes: true });
+    } catch (err) {
+      errors.push({ packAbsPath: packsDir, message: `pack-loader: cannot list probe-packs dir for '${bp.slug}': ${err.message}` });
+      continue;
+    }
+
+    const packFiles = entries
+      .filter((e) => e.isFile() && PACK_FILENAME_RE.test(e.name))
+      .map((e) => join(packsDir, e.name))
+      .sort();
+
+    for (const packAbsPath of packFiles) {
+      let mod;
+      try {
+        mod = await import(pathToFileURL(packAbsPath).href);
+      } catch (err) {
+        errors.push({ packAbsPath, message: `pack-loader: import failed for ${packAbsPath}: ${err.message}` });
+        continue;
+      }
+      const validation = validatePackModule({ mod, blueprintSlug: bp.slug, packAbsPath });
+      if (!validation.ok) {
+        for (const e of validation.errors) errors.push({ packAbsPath, message: e.message });
+        continue;
+      }
+      const pack = validation.pack;
+
+      const badCheckIds = pack.checks
+        .map((c) => c.id)
+        .filter((id) => !contributedAcIds.has(id));
+      if (badCheckIds.length > 0) {
+        errors.push({
+          packAbsPath,
+          message: `pack-loader: pack '${pack.packName}' names checks [${badCheckIds.join(', ')}] that the blueprint '${bp.slug}' does not contribute; contributed AC ids on this blueprint: ${contributedAcIds.size === 0 ? '(none)' : [...contributedAcIds].sort().join(', ')}`,
+        });
+        continue;
+      }
+
+      packs.push({
+        packName: pack.packName,
+        version: pack.version,
+        blueprintSlug: bp.slug,
+        packAbsPath,
+        appliesTo: pack.appliesTo,
+        boot: pack.boot ?? null,
+        checks: pack.checks,
+        preChecks: Array.isArray(pack.preChecks) ? pack.preChecks : [],
+      });
+    }
+  }
+
+  return { packs, warnings, errors };
+}
+
+/**
+ * Read every AC id contributed by a blueprint. A blueprint contributes ACs
+ * inside its US contribution files (`contributions[].kind === 'us'`).
+ *
+ * @param {object} args
+ * @param {string} args.blueprintAbsPath
+ * @returns {Promise<Set<string>>}
+ */
+export async function readContributedAcIds({ blueprintAbsPath }) {
+  const bpJsonPath = join(blueprintAbsPath, 'blueprint.json');
+  const bpRaw = await readFile(bpJsonPath, 'utf8');
+  let bpJson;
+  try { bpJson = JSON.parse(bpRaw); } catch (err) {
+    throw new Error(`invalid JSON in ${bpJsonPath}: ${err.message}`);
+  }
+  const contributions = Array.isArray(bpJson?.contributions) ? bpJson.contributions : [];
+  const acIds = new Set();
+  for (const c of contributions) {
+    if (c?.kind !== 'us' || typeof c.path !== 'string') continue;
+    // blueprint.json contribution paths are relative to the blueprint's
+    // `contributions/` subdirectory (see src/blueprint/loader.js). Older
+    // tests supplied paths that included `contributions/` at the root
+    // instead; probe for both shapes so shelf blueprints and hand-rolled
+    // fixtures both load without a per-caller convention.
+    const insideContributions = resolve(blueprintAbsPath, 'contributions', c.path);
+    const legacyRootRelative = resolve(blueprintAbsPath, c.path);
+    let usAbs = insideContributions;
+    let usRaw;
+    try {
+      usRaw = await readFile(insideContributions, 'utf8');
+    } catch (primaryErr) {
+      try {
+        usRaw = await readFile(legacyRootRelative, 'utf8');
+        usAbs = legacyRootRelative;
+      } catch {
+        throw new Error(`cannot read US contribution ${c.path}: ${primaryErr.message}`);
+      }
+    }
+    let usJson;
+    try {
+      usJson = JSON.parse(usRaw);
+    } catch (err) {
+      throw new Error(`cannot read US contribution ${c.path}: ${err.message}`);
+    }
+    void usAbs;
+    const inlineAcs = Array.isArray(usJson?.acceptanceCriteria) ? usJson.acceptanceCriteria : [];
+    for (const ac of inlineAcs) {
+      if (typeof ac?.id === 'string') acIds.add(ac.id);
+    }
+  }
+  return acIds;
+}
+
+/**
+ * @typedef {object} LoadedPack
+ * @property {string} packName
+ * @property {string} version
+ * @property {string} blueprintSlug
+ * @property {string} packAbsPath
+ * @property {(ctx: { fbs: object, uiBaseline: object|null, manifest: object|null }) => boolean} appliesTo
+ * @property {object|null} boot
+ * @property {Array<{ id: string, severity: 'block'|'warn'|'advisory', description: string, run: (ctx: object) => Promise<{ verdict: 'pass'|'warn'|'fail'|'skipped', detail?: string }>, dependsOn?: string|string[] }>} checks
+ * @property {Array<{ id: string, severity: 'block'|'warn'|'advisory', description: string, run: () => Promise<{ verdict: 'pass'|'warn'|'fail', detail?: string }> }>} preChecks
+ */

package/src/browser-verify/pack-runner.js

@@ -0,0 +1,193 @@
+// Pack pass runner (visual round T-0, US-1701 AC-1701-4 / 6). CN-108.
+//
+// Invokes every applicable loaded pack against a FBS and folds the
+// results into a `probePacks[]` array on the browserVerification
+// record. Applicability is enforced by the pack's own `appliesTo`
+// predicate: a false return records `applicable: false` and no
+// check runs. `preChecks[]` (if any) run first; a failing pre-check
+// causes browser checks that name it under `dependsOn` to record
+// `skipped` with detail `skipped-by-pre-check:<preCheckId>`.
+//
+// The runner is browser-driver-agnostic: the caller injects a
+// `browser` seam (the same shape a pack's `run` expects on its `browser`
+// argument) plus `fetch`, `runtimeUrl` and the route/theme cursor.
+
+/**
+ * Run applicable packs for one FBS.
+ *
+ * @param {object} args
+ * @param {Array<import('./pack-loader.js').LoadedPack>} args.packs
+ * @param {object} args.fbs
+ * @param {object|null} args.uiBaseline
+ * @param {object|null} args.manifest
+ * @param {object|null} args.browser        injected browser (or null in unit tests)
+ * @param {(url: string, init?: object) => Promise<any>|null} args.fetch
+ * @param {string} args.runtimeUrl
+ * @param {Array<object>} args.routes       FBS routes (nav model)
+ * @param {Array<'light'|'dark'>} args.themes
+ * @param {string} [args.packNameFilter]    when set, only packs whose packName === filter are considered
+ * @param {(pack: import('./pack-loader.js').LoadedPack) => object} [args.buildContext]  optional context override for unit tests
+ * @returns {Promise<{ probePacks: Array<object>, packHighestSeverityFail: 'block'|'warn'|null }>}
+ */
+export async function runProbePacksForFbs({
+  packs,
+  fbs,
+  uiBaseline,
+  manifest,
+  projectRoot = null,
+  browser,
+  fetch,
+  runtimeUrl,
+  routes,
+  themes,
+  packNameFilter,
+  buildContext,
+}) {
+  const probePacks = [];
+  let highest = null;
+  const chosen = Array.isArray(packs) ? packs : [];
+  const primaryRoute = Array.isArray(routes) && routes.length > 0 ? routes[0] : null;
+  const primaryTheme = Array.isArray(themes) && themes.length > 0 ? themes[0] : 'light';
+
+  for (const pack of chosen) {
+    if (typeof packNameFilter === 'string' && packNameFilter.length > 0 && pack.packName !== packNameFilter) {
+      continue;
+    }
+
+    let applicable;
+    let applicabilityDetail;
+    try {
+      applicable = Boolean(pack.appliesTo({ fbs, uiBaseline, manifest }));
+    } catch (err) {
+      applicable = false;
+      applicabilityDetail = `appliesTo threw: ${err.message}`;
+    }
+
+    if (!applicable) {
+      probePacks.push({
+        packName: pack.packName,
+        packVersion: pack.version,
+        blueprintSlug: pack.blueprintSlug,
+        applicable: false,
+        ...(applicabilityDetail ? { detail: applicabilityDetail } : { detail: `appliesTo returned false for ${fbs?.fbsId ?? '(no fbs)'}` }),
+        checks: [],
+      });
+      continue;
+    }
+
+    // Pre-checks first.
+    const preCheckRecords = [];
+    const failedPreCheckIds = new Set();
+    for (const pre of pack.preChecks) {
+      let verdict = 'pass';
+      let detail;
+      try {
+        const outcome = await pre.run({ fbs, uiBaseline, manifest, runtimeUrl, fetch, browser });
+        verdict = outcome?.verdict ?? 'pass';
+        detail = outcome?.detail;
+      } catch (err) {
+        verdict = 'fail';
+        detail = `pre-check threw: ${err.message}`;
+      }
+      preCheckRecords.push({
+        id: pre.id,
+        verdict,
+        severity: pre.severity,
+        ...(typeof detail === 'string' && detail.length > 0 ? { detail } : {}),
+      });
+      if (verdict === 'fail') failedPreCheckIds.add(pre.id);
+      if (verdict === 'fail' && pre.severity === 'block') highest = 'block';
+      else if (verdict === 'fail' && pre.severity === 'warn' && highest !== 'block') highest = 'warn';
+    }
+
+    const checkRecords = [];
+    for (const check of pack.checks) {
+      const deps = normaliseDependsOn(check.dependsOn);
+      const failingDep = deps.find((d) => failedPreCheckIds.has(d));
+      if (failingDep) {
+        checkRecords.push({
+          id: check.id,
+          verdict: 'skipped',
+          severity: check.severity,
+          detail: `skipped-by-pre-check:${failingDep}`,
+        });
+        continue;
+      }
+      // Per-check applicability (visual round T-5 spec section 5.5).
+      // A pack check may declare its own `appliesTo` predicate that
+      // reads the applied capability set (from projectRoot) so an
+      // absent capability records `applicable: false` and the
+      // aggregate verdict treats the check as neither pass nor fail.
+      // A check without a predicate always runs (backward compatible
+      // with T-0 through T-4 packs).
+      if (typeof check.appliesTo === 'function') {
+        let checkApplicable;
+        let checkAppliesDetail;
+        try {
+          checkApplicable = Boolean(await check.appliesTo({ fbs, uiBaseline, manifest, projectRoot }));
+        } catch (err) {
+          checkApplicable = false;
+          checkAppliesDetail = `appliesTo threw: ${err.message}`;
+        }
+        if (!checkApplicable) {
+          // Spec section 5.5 says the residual cure records
+          // applicable: false at the check level. rcf-schemas 0.6.1
+          // (browserVerificationProbePackCheck) closes the schema and
+          // still requires a verdict enum, so the manifest write path
+          // refuses a check that carries `applicable: false` alone.
+          // Until the schema minor promotes an `applicable` field at
+          // the check level (follow-up rcf-schemas bump), emit
+          // `verdict: 'skipped'` with a detail naming the applicability
+          // gate. Semantically the aggregate verdict still treats this
+          // as neither pass nor fail (skipped does not raise `highest`).
+          checkRecords.push({
+            id: check.id,
+            verdict: 'skipped',
+            severity: check.severity,
+            detail: checkAppliesDetail ?? 'check appliesTo returned false (required capability not applied)',
+          });
+          continue;
+        }
+      }
+      const context = typeof buildContext === 'function'
+        ? buildContext(pack)
+        : { browser, fetch, runtimeUrl, route: primaryRoute, theme: primaryTheme, projectRoot };
+      let verdict = 'pass';
+      let detail;
+      try {
+        const outcome = await check.run(context);
+        verdict = outcome?.verdict ?? 'pass';
+        detail = outcome?.detail;
+      } catch (err) {
+        verdict = 'fail';
+        detail = `check threw: ${err.message}`;
+      }
+      checkRecords.push({
+        id: check.id,
+        verdict,
+        severity: check.severity,
+        ...(typeof detail === 'string' && detail.length > 0 ? { detail } : {}),
+      });
+      if (verdict === 'fail' && check.severity === 'block') highest = 'block';
+      else if (verdict === 'fail' && check.severity === 'warn' && highest !== 'block') highest = 'warn';
+    }
+
+    const record = {
+      packName: pack.packName,
+      packVersion: pack.version,
+      blueprintSlug: pack.blueprintSlug,
+      applicable: true,
+      checks: checkRecords,
+    };
+    if (preCheckRecords.length > 0) record.preChecks = preCheckRecords;
+    probePacks.push(record);
+  }
+
+  return { probePacks, packHighestSeverityFail: highest };
+}
+
+function normaliseDependsOn(dependsOn) {
+  if (typeof dependsOn === 'string' && dependsOn.length > 0) return [dependsOn];
+  if (Array.isArray(dependsOn)) return dependsOn.filter((d) => typeof d === 'string' && d.length > 0);
+  return [];
+}