@cloverleaf/reference-impl 0.5.1 → 0.5.3

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "cloverleaf",
   "description": "Cloverleaf reference implementation — Claude Code skills for task scaffolding and the Delivery pipeline (implementer, documenter, reviewer, UI reviewer with multi-viewport visual diff, QA, merge).",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "author": {
     "name": "Renato D'Arrigo",
     "email": "renato.darrigo@gmail.com"

package/README.md

@@ -29,7 +29,7 @@ v0.2 implements both paths of the Delivery track:
 | Implementer | Real | Subagent, code + tests on feature branch |
 | Documenter | Real (v0.2) | Subagent, doc-only commits per file-path rules |
 | Reviewer | Real | Subagent, read-only review of diff |
-| UI Reviewer | Real (v0.3) | Playwright + axe-core, diff-scoped to affected routes, single viewport, a11y only |
+| UI Reviewer | Real (v0.5) | Playwright + axe-core + pixelmatch; multi-browser outer loop (chromium/webkit/firefox); axe-core runs on `axe.browser` engine only (default chromium); maxCombinations cap with per-route warnings |
 | QA | Real (v0.2) | Per-package test runner via `git worktree` |
 | Plan | Stub | Deferred to v0.3 |
 | Researcher | Stub | Deferred to v0.3 |
@@ -87,16 +87,32 @@ All overrides are read fresh on every skill invocation; no caching. Edit and the
 ### Known limitations
 
 - Concurrent `/cloverleaf-run` on the same repo may race on preview ports.
-- UI Reviewer visual diff + multi-viewport deferred to v0.4.
 - QA does not produce HTML reports (no `report_uri`).
 
 ### Prerequisites for UI Reviewer
 
-Run once per machine:
+The installer (`install.sh`) automatically runs the Playwright browser install step. If you need to install manually, run:
 
-    npx playwright install chromium
+    npx playwright install chromium webkit firefox
 
-This installs chromium into `~/.cache/ms-playwright/` (the default `PLAYWRIGHT_BROWSERS_PATH`). Subsequent `/cloverleaf-ui-review` invocations reuse this cache — no ~300 MB re-download per run.
+On **Linux**, webkit additionally requires system-level dependencies:
+
+    npx playwright install-deps webkit
+
+**Disk footprint:** approximately 600–650 MB total across all three browsers in the default `PLAYWRIGHT_BROWSERS_PATH` location (`~/.cache/ms-playwright/`).
+
+| Browser   | Approx. size |
+|-----------|-------------|
+| chromium  | ~300 MB     |
+| webkit    | ~150–170 MB |
+| firefox   | ~150–180 MB |
+
+To store browsers in a non-default location, set `PLAYWRIGHT_BROWSERS_PATH` before installing and before running the UI Reviewer skill:
+
+    export PLAYWRIGHT_BROWSERS_PATH=/mnt/data/playwright
+    npx playwright install chromium webkit firefox
+
+Subsequent `/cloverleaf-ui-review` invocations reuse the cache — no re-download per run as long as `PLAYWRIGHT_BROWSERS_PATH` is set consistently.
 
 ## Quick start — toy repo
 
@@ -129,7 +145,7 @@ The Reviewer never switches branches. It reads files via `git show` and runs tes
 
 ## Package layout
 
-- `lib/` — TypeScript library used by the CLI. State, events, feedback, IDs, paths.
+- `lib/` — TypeScript library used by the CLI. State, events, feedback, IDs, paths. Includes `buildBaselinePath(repoRoot, browser, slug, viewport)` (`lib/visual-diff.ts`) for constructing canonical baseline paths under `.cloverleaf/baselines/{browser}/`. `lib/ui-browser.ts` exports `buildBrowserEscalationFinding` and `applyMaxCombinationsCap` (used by the UI Reviewer prompt for per-engine escalation and combination-count capping).
 - `skills/` — Claude Code skill markdown files.
 - `prompts/` — Implementer/Reviewer subagent system prompts.
 - `examples/toy-repo/` — standalone demo repo.

package/VERSION

@@ -1 +1 @@
-0.5.1
+0.5.3

package/config/ui-review.json

@@ -1,4 +1,5 @@
 {
+  "browsers": ["chromium"],
   "viewports": {
     "mobile":  { "width": 375,  "height": 667 },
     "tablet":  { "width": 768,  "height": 1024 },
@@ -12,7 +13,9 @@
   },
   "axe": {
     "viewports": ["desktop"],
+    "browser": "chromium",
     "dedupeBy": ["ruleId", "target"],
     "ignored": []
-  }
+  },
+  "maxCombinations": 90
 }

package/dist/cli.mjs

@@ -26,6 +26,7 @@
  *   materialise-tasks <repoRoot> <planId>
  *   next-work-item-id <repoRoot> <project>
  *   discovery-config --repo-root <repoRoot>
+ *   prep-worktree <mainRoot> <worktreePath>
  */
 import { readFileSync } from 'node:fs';
 import { execSync } from 'node:child_process';
@@ -44,6 +45,7 @@ import { loadRfc, saveRfc, advanceRfcStatus } from './rfc.mjs';
 import { loadSpike, saveSpike, advanceSpikeStatus } from './spike.mjs';
 import { loadPlan, savePlan, advancePlanStatus, materialiseTasksFromPlan } from './plan.mjs';
 import { loadDiscoveryConfig } from './discovery-config.mjs';
+import { prepWorktree } from './prep-worktree.mjs';
 function die(msg, code = 1) {
     process.stderr.write(msg + '\n');
     process.exit(code);
@@ -73,7 +75,8 @@ function usage(msg) {
         '  advance-plan <repoRoot> <id> <toStatus> <agent|human> [gate]\n' +
         '  materialise-tasks <repoRoot> <planId>\n' +
         '  next-work-item-id <repoRoot> <project>\n' +
-        '  discovery-config --repo-root <repoRoot>\n');
+        '  discovery-config --repo-root <repoRoot>\n' +
+        '  prep-worktree <mainRoot> <worktreePath>\n');
     process.exit(2);
 }
 const [, , command, ...rest] = process.argv;
@@ -368,6 +371,13 @@ try {
             process.stdout.write(JSON.stringify(c, null, 2));
             break;
         }
+        case 'prep-worktree': {
+            const [mainRoot, worktreePath] = rest;
+            if (!mainRoot || !worktreePath)
+                usage('prep-worktree requires <mainRoot> <worktreePath>');
+            prepWorktree(mainRoot, worktreePath);
+            break;
+        }
         default:
             usage(`Unknown command: ${command}`);
     }

package/dist/prep-worktree.mjs

@@ -0,0 +1,50 @@
+import { cpSync, existsSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+import { join } from 'node:path';
+/**
+ * Prepare a freshly-created git worktree of the cloverleaf monorepo for running reference-impl
+ * tests. Addresses the v0.5 dogfood finding (CLV-16, CLV-17 Delivery runs) where Reviewer/QA
+ * subagents hit `Cannot find module '@cloverleaf/standard/validators/index.js'` because:
+ *
+ *   1. The worktree has no `node_modules` at all (git worktrees don't inherit it).
+ *   2. Running `npm install` in the worktree's `reference-impl/` follows the `file:../standard`
+ *      dep, but the worktree's `standard/` has no `dist/` (nothing built) and no `node_modules/`
+ *      (ajv-formats etc., needed by the conformance runner).
+ *
+ * Strategy: reuse main's already-installed deps and build standard/ fresh from the worktree
+ * sources so any branch changes to `standard/src` are picked up.
+ *
+ *   - Copy `<main>/standard/node_modules`       → `<wt>/standard/node_modules`
+ *   - Run `npm run build`                       in `<wt>/standard`  (produces worktree dist/)
+ *   - Copy `<main>/reference-impl/node_modules` → `<wt>/reference-impl/node_modules`
+ *     The `@cloverleaf/standard → ../../../standard` relative symlink is preserved verbatim so
+ *     it resolves to the worktree's OWN standard/, not main's.
+ */
+export function prepWorktree(mainRoot, worktreePath) {
+    const mainStandardNm = join(mainRoot, 'standard', 'node_modules');
+    const mainRefImplNm = join(mainRoot, 'reference-impl', 'node_modules');
+    const wtStandardPkg = join(worktreePath, 'standard', 'package.json');
+    const wtRefImplPkg = join(worktreePath, 'reference-impl', 'package.json');
+    if (!existsSync(wtStandardPkg)) {
+        throw new Error(`worktree missing standard/package.json at ${wtStandardPkg}`);
+    }
+    if (!existsSync(wtRefImplPkg)) {
+        throw new Error(`worktree missing reference-impl/package.json at ${wtRefImplPkg}`);
+    }
+    if (!existsSync(mainStandardNm)) {
+        throw new Error(`main missing standard/node_modules at ${mainStandardNm} — run \`npm ci\` in main's standard/ first`);
+    }
+    if (!existsSync(mainRefImplNm)) {
+        throw new Error(`main missing reference-impl/node_modules at ${mainRefImplNm} — run \`npm ci\` in main's reference-impl/ first`);
+    }
+    const wtStandardNm = join(worktreePath, 'standard', 'node_modules');
+    const wtRefImplNm = join(worktreePath, 'reference-impl', 'node_modules');
+    // verbatimSymlinks keeps relative symlink targets byte-identical, so the @cloverleaf/standard
+    // link in reference-impl/node_modules/ resolves against the worktree after copy.
+    cpSync(mainStandardNm, wtStandardNm, { recursive: true, verbatimSymlinks: true });
+    cpSync(mainRefImplNm, wtRefImplNm, { recursive: true, verbatimSymlinks: true });
+    execSync('npm run build', {
+        cwd: join(worktreePath, 'standard'),
+        stdio: 'pipe',
+    });
+}

package/dist/ui-browser.mjs

@@ -0,0 +1,74 @@
+// ---------------------------------------------------------------------------
+// Browser escalation
+// ---------------------------------------------------------------------------
+/**
+ * Build an escalation Finding for a missing Playwright browser binary.
+ *
+ * The finding names the missing engine and includes the install command per
+ * the CLV-9 RFC and CLV-10 spike:
+ *   - All platforms:  `npx playwright install webkit firefox`
+ *   - Linux only:     `npx playwright install-deps webkit`
+ *
+ * @param engine   The browser engine that is missing.
+ * @param platform The platform string (defaults to `process.platform`). Pass
+ *                 "linux" explicitly to include the install-deps hint; all
+ *                 other values are treated as non-Linux.
+ */
+export function buildBrowserEscalationFinding(engine, platform = process.platform) {
+    const isLinux = platform === 'linux';
+    const installCmd = 'npx playwright install webkit firefox';
+    const depsHint = isLinux
+        ? ` On Linux, also run: npx playwright install-deps webkit`
+        : '';
+    return {
+        severity: 'error',
+        rule: 'browser-missing',
+        message: `Playwright ${engine} not installed. Run '${installCmd}' on this machine.${depsHint}`,
+        metadata: { engine, installCommand: installCmd },
+    };
+}
+/**
+ * Enforce the maxCombinations cap.
+ *
+ * When `routes.length × viewportCount × browserCount > maxCombinations`,
+ * the affected routes are sorted by diff size (most-changed first) and only
+ * the first `floor(maxCombinations / (viewportCount × browserCount))` routes
+ * are processed. One `warning`-severity finding with rule `ui-review-cap` is
+ * emitted per skipped route.
+ *
+ * @param routes          Affected routes with their diff sizes.
+ * @param viewportCount   Number of viewports configured.
+ * @param browserCount    Number of browser engines configured.
+ * @param maxCombinations Maximum allowed combinations (routes × viewports × browsers).
+ * @returns               `{ routes, skippedFindings }` ready for use by the reviewer.
+ */
+export function applyMaxCombinationsCap(routes, viewportCount, browserCount, maxCombinations) {
+    const totalCombinations = routes.length * viewportCount * browserCount;
+    if (totalCombinations <= maxCombinations) {
+        return {
+            routes: routes.map((r) => r.route),
+            skippedFindings: [],
+        };
+    }
+    const perRouteSlots = viewportCount * browserCount;
+    const maxRoutes = Math.floor(maxCombinations / perRouteSlots);
+    // Sort most-changed first, then take first maxRoutes routes.
+    const sorted = [...routes].sort((a, b) => b.diffSize - a.diffSize);
+    const kept = sorted.slice(0, maxRoutes);
+    const skipped = sorted.slice(maxRoutes);
+    const skippedFindings = skipped.map((r) => ({
+        severity: 'warning',
+        rule: 'ui-review-cap',
+        message: `Route ${r.route} skipped: combination count ${totalCombinations} exceeds ` +
+            `maxCombinations (${maxCombinations}); review manually or raise the cap.`,
+        metadata: {
+            route: r.route,
+            combinationCount: totalCombinations,
+            maxCombinations,
+        },
+    }));
+    return {
+        routes: kept.map((r) => r.route),
+        skippedFindings,
+    };
+}

package/dist/ui-review-config.mjs

@@ -4,22 +4,58 @@ import { dirname, join } from 'node:path';
 const here = dirname(fileURLToPath(import.meta.url));
 const PACKAGE_DEFAULT = join(here, '..', 'config', 'ui-review.json');
 const HARDCODED_FALLBACK = {
+    browsers: ['chromium'],
     viewports: {
         mobile: { width: 375, height: 667 },
         tablet: { width: 768, height: 1024 },
         desktop: { width: 1280, height: 800 },
     },
     visualDiff: { enabled: true, threshold: 0.1, maxDiffRatio: 0.01, mask: [] },
-    axe: { viewports: ['desktop'], dedupeBy: ['ruleId', 'target'], ignored: [] },
+    axe: {
+        viewports: ['desktop'],
+        browser: 'chromium',
+        dedupeBy: ['ruleId', 'target'],
+        ignored: [],
+    },
+    maxCombinations: 90,
 };
-function readAsConfig(path) {
-    try {
-        const doc = JSON.parse(readFileSync(path, 'utf-8'));
-        // Back-compat: if ignored is missing from an older override, default it.
-        if (doc.axe && !('ignored' in doc.axe)) {
+function applyDefaults(doc) {
+    // browsers — default ["chromium"]
+    if (!Array.isArray(doc.browsers)) {
+        doc.browsers = ['chromium'];
+    }
+    // viewports — fall through to hardcoded if omitted entirely
+    if (!doc.viewports) {
+        doc.viewports = HARDCODED_FALLBACK.viewports;
+    }
+    // visualDiff
+    if (!doc.visualDiff) {
+        doc.visualDiff = { ...HARDCODED_FALLBACK.visualDiff };
+    }
+    // axe sub-fields
+    if (!doc.axe) {
+        doc.axe = { ...HARDCODED_FALLBACK.axe };
+    }
+    else {
+        // Back-compat: ignored omitted in older overrides
+        if (!('ignored' in doc.axe)) {
             doc.axe.ignored = [];
         }
-        return doc;
+        // axe.browser — default "chromium"
+        if (!('browser' in doc.axe)) {
+            doc.axe.browser = 'chromium';
+        }
+    }
+    // maxCombinations — default 90
+    if (typeof doc.maxCombinations !== 'number') {
+        doc.maxCombinations = 90;
+    }
+    return doc;
+}
+function readAsConfig(path) {
+    try {
+        const raw = JSON.parse(readFileSync(path, 'utf-8'));
+        return applyDefaults(raw);
     }
     catch {
         return null;

package/dist/visual-diff.mjs

@@ -1,7 +1,20 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { dirname } from 'node:path';
+import { dirname, join } from 'node:path';
 import pixelmatch from 'pixelmatch';
 import { PNG } from 'pngjs';
+/**
+ * Construct the canonical baseline path for a visual-diff capture.
+ *
+ * Layout (as of CLV-17): `.cloverleaf/baselines/{browser}/{slug}-{viewport}.png`
+ *
+ * The flat layout `.cloverleaf/baselines/{slug}-{viewport}.png` is DEPRECATED.
+ * All new baselines MUST be placed under `baselines/{browser}/`.
+ * Existing flat chromium baselines were migrated to `baselines/chromium/` via
+ * explicit `git mv` in CLV-17.
+ */
+export function buildBaselinePath(repoRoot, browser, slug, viewport) {
+    return join(repoRoot, '.cloverleaf', 'baselines', browser, `${slug}-${viewport}.png`);
+}
 function ensureDir(path) {
     mkdirSync(dirname(path), { recursive: true });
 }

package/install.sh

@@ -42,9 +42,22 @@ echo "  /cloverleaf-merge      — merge gate"
 echo ""
 echo "Restart any open Claude Code sessions to pick up the new skills."
 
-# Post-install: warn about Playwright chromium if not cached
-if [ ! -d "${HOME}/.cache/ms-playwright" ] || [ -z "$(ls -A "${HOME}/.cache/ms-playwright" 2>/dev/null)" ]; then
+# Post-install: install Playwright browsers for UI Reviewer.
+echo ""
+echo "Installing Playwright browsers (chromium, webkit, firefox)..."
+echo "  (approx. 600–650 MB total in \${PLAYWRIGHT_BROWSERS_PATH:-~/.cache/ms-playwright})"
+echo ""
+
+npx playwright install chromium webkit firefox
+
+# On Linux, system deps for webkit are also required.
+if [ "$(uname -s)" = "Linux" ]; then
   echo ""
-  echo "Note: UI Reviewer uses Playwright chromium. If you plan to run /cloverleaf-ui-review, install once with:"
-  echo "  npx playwright install chromium"
+  echo "Linux detected — installing webkit system dependencies..."
+  npx playwright install-deps webkit
 fi
+
+echo ""
+echo "Playwright browsers installed."
+echo "To use a custom cache directory, set PLAYWRIGHT_BROWSERS_PATH before running install."
+echo "  e.g. PLAYWRIGHT_BROWSERS_PATH=~/.cache/ms-playwright ./install.sh"

package/lib/cli.ts

@@ -26,6 +26,7 @@
  *   materialise-tasks <repoRoot> <planId>
  *   next-work-item-id <repoRoot> <project>
  *   discovery-config --repo-root <repoRoot>
+ *   prep-worktree <mainRoot> <worktreePath>
  */
 
 import { readFileSync } from 'node:fs';
@@ -46,6 +47,7 @@ import { loadRfc, saveRfc, advanceRfcStatus, type RfcDoc } from './rfc.js';
 import { loadSpike, saveSpike, advanceSpikeStatus, type SpikeDoc } from './spike.js';
 import { loadPlan, savePlan, advancePlanStatus, materialiseTasksFromPlan, type PlanDoc } from './plan.js';
 import { loadDiscoveryConfig } from './discovery-config.js';
+import { prepWorktree } from './prep-worktree.js';
 
 function die(msg: string, code = 1): never {
   process.stderr.write(msg + '\n');
@@ -77,7 +79,8 @@ function usage(msg?: string): never {
       '  advance-plan <repoRoot> <id> <toStatus> <agent|human> [gate]\n' +
       '  materialise-tasks <repoRoot> <planId>\n' +
       '  next-work-item-id <repoRoot> <project>\n' +
-      '  discovery-config --repo-root <repoRoot>\n'
+      '  discovery-config --repo-root <repoRoot>\n' +
+      '  prep-worktree <mainRoot> <worktreePath>\n'
   );
   process.exit(2);
 }
@@ -375,6 +378,13 @@ try {
       break;
     }
 
+    case 'prep-worktree': {
+      const [mainRoot, worktreePath] = rest;
+      if (!mainRoot || !worktreePath) usage('prep-worktree requires <mainRoot> <worktreePath>');
+      prepWorktree(mainRoot, worktreePath);
+      break;
+    }
+
     default:
       usage(`Unknown command: ${command}`);
   }

package/lib/prep-worktree.ts

@@ -0,0 +1,55 @@
+import { cpSync, existsSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+import { join } from 'node:path';
+
+/**
+ * Prepare a freshly-created git worktree of the cloverleaf monorepo for running reference-impl
+ * tests. Addresses the v0.5 dogfood finding (CLV-16, CLV-17 Delivery runs) where Reviewer/QA
+ * subagents hit `Cannot find module '@cloverleaf/standard/validators/index.js'` because:
+ *
+ *   1. The worktree has no `node_modules` at all (git worktrees don't inherit it).
+ *   2. Running `npm install` in the worktree's `reference-impl/` follows the `file:../standard`
+ *      dep, but the worktree's `standard/` has no `dist/` (nothing built) and no `node_modules/`
+ *      (ajv-formats etc., needed by the conformance runner).
+ *
+ * Strategy: reuse main's already-installed deps and build standard/ fresh from the worktree
+ * sources so any branch changes to `standard/src` are picked up.
+ *
+ *   - Copy `<main>/standard/node_modules`       → `<wt>/standard/node_modules`
+ *   - Run `npm run build`                       in `<wt>/standard`  (produces worktree dist/)
+ *   - Copy `<main>/reference-impl/node_modules` → `<wt>/reference-impl/node_modules`
+ *     The `@cloverleaf/standard → ../../../standard` relative symlink is preserved verbatim so
+ *     it resolves to the worktree's OWN standard/, not main's.
+ */
+export function prepWorktree(mainRoot: string, worktreePath: string): void {
+  const mainStandardNm = join(mainRoot, 'standard', 'node_modules');
+  const mainRefImplNm = join(mainRoot, 'reference-impl', 'node_modules');
+  const wtStandardPkg = join(worktreePath, 'standard', 'package.json');
+  const wtRefImplPkg = join(worktreePath, 'reference-impl', 'package.json');
+
+  if (!existsSync(wtStandardPkg)) {
+    throw new Error(`worktree missing standard/package.json at ${wtStandardPkg}`);
+  }
+  if (!existsSync(wtRefImplPkg)) {
+    throw new Error(`worktree missing reference-impl/package.json at ${wtRefImplPkg}`);
+  }
+  if (!existsSync(mainStandardNm)) {
+    throw new Error(`main missing standard/node_modules at ${mainStandardNm} — run \`npm ci\` in main's standard/ first`);
+  }
+  if (!existsSync(mainRefImplNm)) {
+    throw new Error(`main missing reference-impl/node_modules at ${mainRefImplNm} — run \`npm ci\` in main's reference-impl/ first`);
+  }
+
+  const wtStandardNm = join(worktreePath, 'standard', 'node_modules');
+  const wtRefImplNm = join(worktreePath, 'reference-impl', 'node_modules');
+
+  // verbatimSymlinks keeps relative symlink targets byte-identical, so the @cloverleaf/standard
+  // link in reference-impl/node_modules/ resolves against the worktree after copy.
+  cpSync(mainStandardNm, wtStandardNm, { recursive: true, verbatimSymlinks: true });
+  cpSync(mainRefImplNm, wtRefImplNm, { recursive: true, verbatimSymlinks: true });
+
+  execSync('npm run build', {
+    cwd: join(worktreePath, 'standard'),
+    stdio: 'pipe',
+  });
+}

package/lib/ui-browser.ts

@@ -0,0 +1,122 @@
+import type { Finding } from './feedback.js';
+import type { BrowserEngine } from './ui-review-config.js';
+
+// ---------------------------------------------------------------------------
+// Browser escalation
+// ---------------------------------------------------------------------------
+
+/**
+ * Build an escalation Finding for a missing Playwright browser binary.
+ *
+ * The finding names the missing engine and includes the install command per
+ * the CLV-9 RFC and CLV-10 spike:
+ *   - All platforms:  `npx playwright install webkit firefox`
+ *   - Linux only:     `npx playwright install-deps webkit`
+ *
+ * @param engine   The browser engine that is missing.
+ * @param platform The platform string (defaults to `process.platform`). Pass
+ *                 "linux" explicitly to include the install-deps hint; all
+ *                 other values are treated as non-Linux.
+ */
+export function buildBrowserEscalationFinding(
+  engine: BrowserEngine,
+  platform: string = process.platform,
+): Finding {
+  const isLinux = platform === 'linux';
+  const installCmd = 'npx playwright install webkit firefox';
+  const depsHint = isLinux
+    ? ` On Linux, also run: npx playwright install-deps webkit`
+    : '';
+  return {
+    severity: 'error',
+    rule: 'browser-missing',
+    message:
+      `Playwright ${engine} not installed. Run '${installCmd}' on this machine.${depsHint}`,
+    metadata: { engine, installCommand: installCmd },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// maxCombinations cap enforcement
+// ---------------------------------------------------------------------------
+
+/**
+ * Represents an affected route with a diff-size weight used for sorting
+ * when maxCombinations cap is applied.
+ */
+export interface RouteWithDiffSize {
+  route: string;
+  /** Number of changed lines (or any monotonic proxy for diff size). */
+  diffSize: number;
+}
+
+/**
+ * Result of applying the maxCombinations cap.
+ */
+export interface CapResult {
+  /** Routes that should be processed (up to the cap). */
+  routes: string[];
+  /**
+   * One `warning`-severity Finding per skipped route, with rule
+   * `ui-review-cap` and a message containing the route name plus the
+   * combination count vs cap.
+   */
+  skippedFindings: Finding[];
+}
+
+/**
+ * Enforce the maxCombinations cap.
+ *
+ * When `routes.length × viewportCount × browserCount > maxCombinations`,
+ * the affected routes are sorted by diff size (most-changed first) and only
+ * the first `floor(maxCombinations / (viewportCount × browserCount))` routes
+ * are processed. One `warning`-severity finding with rule `ui-review-cap` is
+ * emitted per skipped route.
+ *
+ * @param routes          Affected routes with their diff sizes.
+ * @param viewportCount   Number of viewports configured.
+ * @param browserCount    Number of browser engines configured.
+ * @param maxCombinations Maximum allowed combinations (routes × viewports × browsers).
+ * @returns               `{ routes, skippedFindings }` ready for use by the reviewer.
+ */
+export function applyMaxCombinationsCap(
+  routes: RouteWithDiffSize[],
+  viewportCount: number,
+  browserCount: number,
+  maxCombinations: number,
+): CapResult {
+  const totalCombinations = routes.length * viewportCount * browserCount;
+
+  if (totalCombinations <= maxCombinations) {
+    return {
+      routes: routes.map((r) => r.route),
+      skippedFindings: [],
+    };
+  }
+
+  const perRouteSlots = viewportCount * browserCount;
+  const maxRoutes = Math.floor(maxCombinations / perRouteSlots);
+
+  // Sort most-changed first, then take first maxRoutes routes.
+  const sorted = [...routes].sort((a, b) => b.diffSize - a.diffSize);
+  const kept = sorted.slice(0, maxRoutes);
+  const skipped = sorted.slice(maxRoutes);
+
+  const skippedFindings: Finding[] = skipped.map((r) => ({
+    severity: 'warning',
+    rule: 'ui-review-cap',
+    message:
+      `Route ${r.route} skipped: combination count ${totalCombinations} exceeds ` +
+      `maxCombinations (${maxCombinations}); review manually or raise the cap.`,
+    metadata: {
+      route: r.route,
+      combinationCount: totalCombinations,
+      maxCombinations,
+    },
+  }));
+
+  return {
+    routes: kept.map((r) => r.route),
+    skippedFindings,
+  };
+}

package/lib/ui-review-config.ts

@@ -10,7 +10,12 @@ export interface Viewport {
   height: number;
 }
 
+/** Valid Playwright browser engine strings. */
+export type BrowserEngine = 'chromium' | 'webkit' | 'firefox';
+
 export interface UiReviewConfig {
+  /** Browser engines to run visual-diff + axe across. Default: ["chromium"]. */
+  browsers: BrowserEngine[];
   viewports: Record<string, Viewport>;
   visualDiff: {
     enabled: boolean;
@@ -20,29 +25,78 @@ export interface UiReviewConfig {
   };
   axe: {
     viewports: string[];
+    /** Browser engine to use for axe accessibility runs. Default: "chromium". */
+    browser: BrowserEngine;
     dedupeBy: ('ruleId' | 'target')[];
     ignored: Array<{ ruleId: string; target: string }>;
   };
+  /**
+   * Maximum number of (browser × viewport) combinations to run.
+   * The skill will skip combinations beyond this limit to avoid runaway runtimes.
+   * Default: 90.
+   */
+  maxCombinations: number;
 }
 
 const HARDCODED_FALLBACK: UiReviewConfig = {
+  browsers: ['chromium'],
   viewports: {
     mobile:  { width: 375,  height: 667  },
     tablet:  { width: 768,  height: 1024 },
     desktop: { width: 1280, height: 800  },
   },
   visualDiff: { enabled: true, threshold: 0.1, maxDiffRatio: 0.01, mask: [] },
-  axe: { viewports: ['desktop'], dedupeBy: ['ruleId', 'target'], ignored: [] },
+  axe: {
+    viewports: ['desktop'],
+    browser: 'chromium',
+    dedupeBy: ['ruleId', 'target'],
+    ignored: [],
+  },
+  maxCombinations: 90,
 };
 
-function readAsConfig(path: string): UiReviewConfig | null {
-  try {
-    const doc = JSON.parse(readFileSync(path, 'utf-8')) as UiReviewConfig;
-    // Back-compat: if ignored is missing from an older override, default it.
-    if (doc.axe && !('ignored' in doc.axe)) {
+function applyDefaults(doc: Partial<UiReviewConfig>): UiReviewConfig {
+  // browsers — default ["chromium"]
+  if (!Array.isArray(doc.browsers)) {
+    (doc as UiReviewConfig).browsers = ['chromium'];
+  }
+
+  // viewports — fall through to hardcoded if omitted entirely
+  if (!doc.viewports) {
+    (doc as UiReviewConfig).viewports = HARDCODED_FALLBACK.viewports;
+  }
+
+  // visualDiff
+  if (!doc.visualDiff) {
+    (doc as UiReviewConfig).visualDiff = { ...HARDCODED_FALLBACK.visualDiff };
+  }
+
+  // axe sub-fields
+  if (!doc.axe) {
+    (doc as UiReviewConfig).axe = { ...HARDCODED_FALLBACK.axe };
+  } else {
+    // Back-compat: ignored omitted in older overrides
+    if (!('ignored' in doc.axe)) {
       (doc.axe as UiReviewConfig['axe']).ignored = [];
     }
-    return doc;
+    // axe.browser — default "chromium"
+    if (!('browser' in doc.axe)) {
+      (doc.axe as UiReviewConfig['axe']).browser = 'chromium';
+    }
+  }
+
+  // maxCombinations — default 90
+  if (typeof doc.maxCombinations !== 'number') {
+    (doc as UiReviewConfig).maxCombinations = 90;
+  }
+
+  return doc as UiReviewConfig;
+}
+
+function readAsConfig(path: string): UiReviewConfig | null {
+  try {
+    const raw = JSON.parse(readFileSync(path, 'utf-8')) as Partial<UiReviewConfig>;
+    return applyDefaults(raw);
   } catch {
     return null;
   }

package/lib/visual-diff.ts

@@ -1,10 +1,29 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { dirname } from 'node:path';
+import { dirname, join } from 'node:path';
 import pixelmatch from 'pixelmatch';
 import { PNG } from 'pngjs';
 
 export type VisualDiffStatus = 'new-baseline' | 'match' | 'diff' | 'dimension-mismatch';
 
+/**
+ * Construct the canonical baseline path for a visual-diff capture.
+ *
+ * Layout (as of CLV-17): `.cloverleaf/baselines/{browser}/{slug}-{viewport}.png`
+ *
+ * The flat layout `.cloverleaf/baselines/{slug}-{viewport}.png` is DEPRECATED.
+ * All new baselines MUST be placed under `baselines/{browser}/`.
+ * Existing flat chromium baselines were migrated to `baselines/chromium/` via
+ * explicit `git mv` in CLV-17.
+ */
+export function buildBaselinePath(
+  repoRoot: string,
+  browser: string,
+  slug: string,
+  viewport: string,
+): string {
+  return join(repoRoot, '.cloverleaf', 'baselines', browser, `${slug}-${viewport}.png`);
+}
+
 export interface VisualDiffResult {
   status: VisualDiffStatus;
   diffPixels: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloverleaf/reference-impl",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "Reference implementation of the Cloverleaf methodology as Claude Code skills. Implements the Tight Loop (Implementer + Reviewer).",
   "type": "module",
   "license": "MIT",

package/prompts/documenter.md

@@ -52,10 +52,23 @@ If `## [Unreleased]` does not exist, create it at the top of the CHANGELOG (righ
 
 ## Commit discipline
 
-- One commit per file touched.
+- **Before committing, run `git status --porcelain` in the worktree and stage every modified doc file.** Do NOT hardcode a single path into `git add`; the subagent has historically forgotten README.md and committed only CHANGELOG.md when it edited both. The reliable pattern:
+
+  ```bash
+  cd <temp>
+  git status --porcelain
+  # For each modified doc file listed, stage it explicitly:
+  git add <package>/CHANGELOG.md <package>/README.md <package>/docs/*.md  # include all that were edited
+  git commit -m "docs(<scope>): <short>"
+  ```
+
+  Equivalently, if you are certain only doc files are modified (you never touched source code), `git add -A` is acceptable — it's the hardcoded-single-path pattern that must be avoided.
+
+- One commit per Documenter run, covering every doc file edited in that run. (If you need multiple scopes — e.g., both `standard/CHANGELOG.md` and `reference-impl/CHANGELOG.md` — make one commit per scope, but each commit still stages every edited file within that scope.)
 - Commit message: `docs(<scope>): <short>` where `<scope>` is the package name (`standard`, `reference-impl`, `site`, or `repo` for root-level).
 - All commits land on `{{branch}}` (the feature branch).
 - After all commits land, run `git worktree remove --force <temp>` to clean up.
+- **Self-check before returning**: `git status --porcelain` in the worktree must be empty. If it's not, you have uncommitted doc edits — stage and commit them, or revert them, before reporting back.
 
 ## Output
 

package/prompts/qa.md

@@ -17,10 +17,15 @@ The Standard's QA contract requires a `preview_uri`. You were passed the sentine
 
 ## Runtime procedure
 
-1. Set up isolated worktree:
+1. Set up isolated worktree and prepare its node_modules + standard/dist. The `prep-worktree`
+   helper copies main's `standard/node_modules` and `reference-impl/node_modules` into the
+   worktree and runs the standard build script so the @cloverleaf/standard symlink resolves
+   correctly inside the worktree. (Without this, `tsc` fails with `Cannot find module
+   '@cloverleaf/standard/validators/index.js'` because git worktrees don't inherit node_modules.)
    ```bash
    TMPDIR=$(mktemp -d)
    git worktree add "$TMPDIR" {{branch}}
+   cloverleaf-cli prep-worktree {{repo_root}} "$TMPDIR"
    ```
 
 2. Inspect the changed files (from the diff). For each QA rule whose `match` patterns match ≥1 changed file, queue its command.

package/prompts/reviewer.md

@@ -41,12 +41,14 @@ A `pass` verdict MAY have an empty `findings` array or omit it. A `bounce` verdi
 - You are a fresh pair of eyes. Do not rubber-stamp. If you have substantive doubts, bounce.
 - Check that tests actually cover the AC; a passing test suite with no AC coverage is a bounce.
 - Do NOT modify any files. You are read-only.
-- Do NOT use `git checkout` or `git switch`. Read files via `git show <branch>:<path>`. If you need a live checkout to run tests, use a worktree:
+- Do NOT use `git checkout` or `git switch`. Read files via `git show <branch>:<path>`. If you need a live checkout to run tests, use a worktree and prime it with `cloverleaf-cli prep-worktree` (copies main's node_modules + builds standard/dist inside the worktree — without this, `tsc` fails with `Cannot find module '@cloverleaf/standard/validators/index.js'`):
 
   ```bash
+  MAIN=$(pwd)
   git worktree add /tmp/cl-review-<task-id> cloverleaf/<task-id>
-  cd /tmp/cl-review-<task-id>
-  npm install && npm test
+  cloverleaf-cli prep-worktree "$MAIN" /tmp/cl-review-<task-id>
+  cd /tmp/cl-review-<task-id>/reference-impl
+  npm test
   cd -
   git worktree remove /tmp/cl-review-<task-id>
   ```

package/prompts/ui-reviewer.md

@@ -1,6 +1,6 @@
 # UI Reviewer Agent
 
-You are the Cloverleaf UI Reviewer. Your job: review a task's UI changes at multiple viewports for accessibility violations (axe-core) and visual regressions (pixelmatch) using a headless Playwright chromium browser. You are read-only for source code and tests — but you DO write baseline/diff artifacts under `.cloverleaf/` on the feature branch.
+You are the Cloverleaf UI Reviewer. Your job: review a task's UI changes at multiple viewports and browser engines for accessibility violations (axe-core) and visual regressions (pixelmatch) using headless Playwright browsers. You are read-only for source code and tests — but you DO write baseline/diff artifacts under `.cloverleaf/` on the feature branch.
 
 ## Input
 
@@ -11,7 +11,7 @@ You are the Cloverleaf UI Reviewer. Your job: review a task's UI changes at mult
 - **Diff from base**: {{diff}}
 - **Preview port**: {{preview_port}} (an already-allocated free local port; use it for the dev server)
 - **Affected routes**: {{affected_routes}} — either a JSON array of route paths (e.g., `["/faq/"]`), or the string `"all"`, or `[]`
-- **UI review config**: {{ui_review_config}} — the loaded `UiReviewConfig` object (viewports, visualDiff, axe) as JSON. The `viewports` array contains named entries such as `mobile`, `tablet`, and `desktop` with their respective `{ width, height }` dimensions.
+- **UI review config**: {{ui_review_config}} — the loaded `UiReviewConfig` object (browsers, viewports, visualDiff, axe, maxCombinations) as JSON. The `viewports` array contains named entries such as `mobile`, `tablet`, and `desktop` with their respective `{ width, height }` dimensions.
 
 ## Paths
 
@@ -24,22 +24,46 @@ You operate in two filesystem locations — keep them straight:
 
 The rationale: baselines on `{{repo_root}}/.cloverleaf/baselines/` get picked up by subsequent `git add` + `git commit` steps in the UI Reviewer, which run on the feature branch. The merge skill (v0.4.1+) then merges those commits to main via `git merge --no-ff`. Writing to the worktree's `.cloverleaf/` would strand the files and `git worktree remove --force` would discard them on teardown.
 
-## Scope (v0.4)
+## Scope (v0.5)
 
-- **Accessibility (axe-core):** run at the viewports listed in `{{ui_review_config}}.axe.viewports`.
+- **Browsers**: the reviewer runs separate Playwright sessions for each engine listed in `{{ui_review_config}}.browsers` (e.g., `["chromium", "webkit", "firefox"]`). Browser is the **outermost** loop, wrapping the viewport × route loops.
+- **Accessibility (axe-core):** run only for the engine specified by `{{ui_review_config}}.axe.browser` (default: `"chromium"`). webkit and firefox browser passes produce **no axe output and no axe findings** — this is intentional, to avoid engine-specific false positives from getComputedStyle, aria-required-children, and scrollable-region-focusable divergence across Blink, WebKit, and Gecko (see CLV-12 spike).
   Apply the allowlist in `{{ui_review_config}}.axe.ignored` to drop pre-existing violations that the consumer has accepted (e.g., a11y debt being tracked separately).
   Dedupe findings across viewports by the `{{ui_review_config}}.axe.dedupeBy` composite key (default `["ruleId", "target"]`).
   Emit one finding per (ruleId, target) pair, with a `metadata.viewports` array aggregating the viewports where the violation was detected.
-- **Visual diff (pixelmatch):** when `{{ui_review_config}}.visualDiff.enabled` is true, screenshot each route at each viewport in `{{ui_review_config}}.viewports`, compare to `.cloverleaf/baselines/{route-slug}-{viewport}.png`, emit `severity: "info"` findings with baseline/candidate/diff attachments when the diff ratio exceeds `maxDiffRatio`.
+- **Visual diff (pixelmatch):** when `{{ui_review_config}}.visualDiff.enabled` is true, screenshot each route at each viewport in `{{ui_review_config}}.viewports` for **each browser**, compare to `.cloverleaf/baselines/{browser}/{route-slug}-{viewport}.png`, emit `severity: "info"` findings with baseline/candidate/diff attachments when the diff ratio exceeds `maxDiffRatio`.
 - Visual diffs are **informational**, never gating. A diff does not fail the review — it surfaces to the human final-gate reviewer.
 - Route empty-set / "all" handling preserves v0.3 behavior:
   - `{{affected_routes}}` is `[]` → `verdict: "pass"`, summary `"No renderable routes affected, skipping axe."`, do NOT start the preview server.
-  - `{{affected_routes}}` is `"all"` → crawl up to 20 pages reachable from `/` via same-origin link discovery (v0.2 fallback).
+  - `{{affected_routes}}` is `"all"` → crawl up to 20 pages reachable from `/` via same-origin link discovery (v0.2 fallback behavior).
   - otherwise → visit exactly the URLs listed.
 
+## maxCombinations cap
+
+Before starting any browser session, compute total combinations = `routes × viewports × browsers`.
+
+If the product exceeds `{{ui_review_config}}.maxCombinations` (default 90):
+1. Sort affected routes by diff size (most-changed first — use the character count of each route's section in `{{diff}}` as a proxy for diff size).
+2. Keep only the first `floor(maxCombinations / (viewportCount × browserCount))` routes.
+3. For each skipped route emit one `severity: "warning"` finding with `rule: "ui-review-cap"` and message:
+   `"Route {route} skipped: combination count {total} exceeds maxCombinations ({cap}); review manually or raise the cap."`
+   Include `metadata: { route, combinationCount: total, maxCombinations: cap }`.
+
+The cap enforcement helper is available in `lib/ui-browser.ts` as `applyMaxCombinationsCap`.
+
 ## Playwright cache
 
-The `PLAYWRIGHT_BROWSERS_PATH` environment variable is set to `~/.cache/ms-playwright` before you are invoked. If the browser is missing, return `verdict: "escalate"` with a synthetic finding: `"Playwright chromium not installed. Run 'npx playwright install chromium' on this machine."`
+The `PLAYWRIGHT_BROWSERS_PATH` environment variable is set to `~/.cache/ms-playwright` before you are invoked. Before launching each browser session, verify that the required engine binary exists in `PLAYWRIGHT_BROWSERS_PATH`. If a browser binary is absent, return `verdict: "escalate"` with a synthetic finding per missing engine:
+
+```
+"Playwright {engine} not installed. Run 'npx playwright install webkit firefox' on this machine."
+```
+
+On Linux, append: `" On Linux, also run: npx playwright install-deps webkit"`
+
+The escalation helper is available in `lib/ui-browser.ts` as `buildBrowserEscalationFinding`.
+
+Do not attempt to launch a missing engine — fail fast with `verdict: "escalate"` listing all missing engines before any browser session is started.
 
 ## Runtime procedure
 
@@ -49,6 +73,7 @@ The `PLAYWRIGHT_BROWSERS_PATH` environment variable is set to `~/.cache/ms-playw
    ```bash
    TMPDIR=$(mktemp -d)
    git worktree add "$TMPDIR" {{branch}}
+   npx cloverleaf-cli prep-worktree {{repo_root}} "$TMPDIR"
    ```
 
 3. For this repo, UI lives in `site/` (or another directory if ui-paths.json scopes it elsewhere). Install dependencies and start the dev server:
@@ -66,53 +91,72 @@ The `PLAYWRIGHT_BROWSERS_PATH` environment variable is set to `~/.cache/ms-playw
    2. Otherwise, attempt to locate and parse an astro config file (common locations: `site/astro.config.mjs`, `astro.config.mjs` at repo root, `apps/web/astro.config.mjs`). Best-effort fallback.
    3. If both fail, treat base as empty string.
 
-6. **Visual-diff pass (when `visualDiff.enabled` is true):**
-   For each route in `{{affected_routes}}` (or the crawl set) × each viewport in `{{ui_review_config}}.viewports`:
-   - Set Playwright viewport to `{ width, height }` from the config.
-   - Apply mask CSS — inject a style that sets `visibility: hidden` on any selector in `visualDiff.mask`.
-   - Navigate to `http://localhost:{{preview_port}}<base><route>`. If 404, retry without the base.
-   - `page.screenshot({ fullPage: false })` → candidate PNG buffer.
-   - Compute slug for the route (lowercase, strip leading/trailing slashes, replace slashes with hyphens; `/` → `index`).
-   - Note: use `{{repo_root}}` (the absolute main-repo path), NOT `$TMPDIR` or the worktree. See the "Paths" section.
-   - Call `compareVisual` (from `lib/visual-diff.ts`) with:
-     - `baselinePath = {{repo_root}}/.cloverleaf/baselines/{slug}-{viewport}.png`
-     - `candidateBuf = <candidate PNG>`
-     - `diffPath = {{repo_root}}/.cloverleaf/runs/{taskId}/ui-review/diff-{slug}-{viewport}.png`
-     - `candidateOutPath = {{repo_root}}/.cloverleaf/runs/{taskId}/ui-review/candidate-{slug}-{viewport}.png`
-     - `threshold = visualDiff.threshold`
-     - `maxDiffRatio = visualDiff.maxDiffRatio`
-   - Map result to a finding:
-     - `new-baseline` → `severity: "info"`, `rule: "visual-diff"`, `message: "new baseline established for {route} @ {viewport}"`, `metadata: { route, viewport, status: "new-baseline" }`. No attachments.
-     - `dimension-mismatch` → `severity: "info"`, `rule: "visual-diff"`, `message: "baseline dimensions changed for {route} @ {viewport}; regenerated"`, `metadata: { route, viewport, status: "dimension-mismatch" }`.
-     - `diff` → `severity: "info"`, `rule: "visual-diff"`, `message: "visual diff: {route} @ {viewport} — {diffRatio*100}% pixels differ"`, `metadata: { route, viewport, diffRatio, status: "diff" }`, `attachments: [baseline, candidate, diff]`.
-     - `match` → no finding emitted.
-
-7. **Axe pass:**
-   For each viewport in `{{ui_review_config}}.axe.viewports`:
-   - Set Playwright viewport to `{ width, height }`.
-   - For each route in `{{affected_routes}}` (or crawl set):
-     - Navigate.
-     - Inject and run axe-core:
-       ```javascript
-       import axe from 'axe-core';
-       const results = await axe.run(document);
-       ```
-     - Collect each violation as a raw tuple: `{ viewport, ruleId, target, impact, message, helpUrl }` (from `axe.run` output).
-
-8. Dedupe raw axe findings via `dedupeAxeFindings(raws, {{ui_review_config}}.axe.dedupeBy, {{ui_review_config}}.axe.ignored)` (from `lib/axe-dedupe.ts`). The `ignored` parameter drops any finding whose `(ruleId, target)` exactly matches an allowlist entry BEFORE dedupe/grouping. Emit the returned `Finding[]`.
-
-9. Severity mapping (preserved from v0.3 via `dedupeAxeFindings`):
-   - axe `impact: "critical"` → `severity: "blocker"`
-   - axe `impact: "serious"` → `severity: "error"`
-   - axe `impact: "moderate"` → `severity: "warning"`
-   - axe `impact: "minor"` → `severity: "info"`
-
-10. Compute verdict (visual-diff findings are **never** considered for gating):
-    - `pass` — zero non-visual-diff findings with severity `blocker` or `error`
-    - `bounce` — ≥1 non-visual-diff finding with severity `blocker` or `error`
-    - `escalate` — preview server failed to start, OR axe threw ≥3 consecutive times, OR Playwright chromium missing.
-
-11. Teardown:
+6. **Apply maxCombinations cap** (when `affected_routes` is a list, not `"all"`):
+   - Compute `routes × viewports × browsers`. Use diff line counts as proxy for route diff size.
+   - Call `applyMaxCombinationsCap` from `lib/ui-browser.ts`.
+   - The `skippedFindings` are collected now and included in the final output.
+   - Use only the returned `routes` list for the browser passes below.
+
+7. **Verify browser binaries** — before starting any browser session:
+   - Check each engine in `{{ui_review_config}}.browsers` against `PLAYWRIGHT_BROWSERS_PATH`.
+   - Collect all missing engines.
+   - If any engine is missing, call `buildBrowserEscalationFinding(engine, process.platform)` for each, teardown the worktree (step 11), and return `verdict: "escalate"` with those findings.
+
+8. **Per-browser outer loop** — for each `browser` in `{{ui_review_config}}.browsers`:
+
+   a. Launch a Playwright browser context using the `browser` engine.
+
+   b. **Visual-diff pass (when `visualDiff.enabled` is true):**
+      For each route in the (capped) route list × each viewport in `{{ui_review_config}}.viewports`:
+      - Set Playwright viewport to `{ width, height }` from the config.
+      - Apply mask CSS — inject a style that sets `visibility: hidden` on any selector in `visualDiff.mask`.
+      - Navigate to `http://localhost:{{preview_port}}<base><route>`. If 404, retry without the base.
+      - `page.screenshot({ fullPage: false })` → candidate PNG buffer.
+      - Compute slug for the route (lowercase, strip leading/trailing slashes, replace slashes with hyphens; `/` → `index`).
+      - Note: use `{{repo_root}}` (the absolute main-repo path), NOT `$TMPDIR` or the worktree. See the "Paths" section.
+      - Call `compareVisual` (from `lib/visual-diff.ts`) with:
+        - `baselinePath = {{repo_root}}/.cloverleaf/baselines/{browser}/{slug}-{viewport}.png`
+        - `candidateBuf = <candidate PNG>`
+        - `diffPath = {{repo_root}}/.cloverleaf/runs/{taskId}/ui-review/diff-{slug}-{viewport}.png`
+        - `candidateOutPath = {{repo_root}}/.cloverleaf/runs/{taskId}/ui-review/candidate-{slug}-{viewport}.png`
+        - `threshold = visualDiff.threshold`
+        - `maxDiffRatio = visualDiff.maxDiffRatio`
+      - Map result to a finding:
+        - `new-baseline` → `severity: "info"`, `rule: "visual-diff"`, `message: "new baseline established for {route} @ {viewport} [{browser}]"`, `metadata: { route, viewport, browser, status: "new-baseline" }`. No attachments.
+        - `dimension-mismatch` → `severity: "info"`, `rule: "visual-diff"`, `message: "baseline dimensions changed for {route} @ {viewport} [{browser}]; regenerated"`, `metadata: { route, viewport, browser, status: "dimension-mismatch" }`.
+        - `diff` → `severity: "info"`, `rule: "visual-diff"`, `message: "visual diff: {route} @ {viewport} [{browser}] — {diffRatio*100}% pixels differ"`, `metadata: { route, viewport, browser, diffRatio, status: "diff" }`, `attachments: [baseline, candidate, diff]`.
+        - `match` → no finding emitted.
+
+   c. **Axe pass (only when `browser === {{ui_review_config}}.axe.browser`):**
+      Skip this section entirely if the current browser is NOT the configured `axe.browser`. webkit and firefox runs produce no axe output and no axe findings.
+
+      For each viewport in `{{ui_review_config}}.axe.viewports`:
+      - Set Playwright viewport to `{ width, height }`.
+      - For each route in the (capped) route list:
+        - Navigate.
+        - Inject and run axe-core:
+          ```javascript
+          import axe from 'axe-core';
+          const results = await axe.run(document);
+          ```
+        - Collect each violation as a raw tuple: `{ viewport, ruleId, target, impact, message, helpUrl }` (from `axe.run` output).
+
+   d. Close the browser context before launching the next engine.
+
+9. Dedupe raw axe findings via `dedupeAxeFindings(raws, {{ui_review_config}}.axe.dedupeBy, {{ui_review_config}}.axe.ignored)` (from `lib/axe-dedupe.ts`). The `ignored` parameter drops any finding whose `(ruleId, target)` exactly matches an allowlist entry BEFORE dedupe/grouping. Emit the returned `Finding[]`.
+
+10. Severity mapping (preserved from v0.3 via `dedupeAxeFindings`):
+    - axe `impact: "critical"` → `severity: "blocker"`
+    - axe `impact: "serious"` → `severity: "error"`
+    - axe `impact: "moderate"` → `severity: "warning"`
+    - axe `impact: "minor"` → `severity: "info"`
+
+11. Compute verdict (visual-diff and ui-review-cap findings are **never** considered for gating):
+    - `pass` — zero non-visual-diff, non-cap findings with severity `blocker` or `error`
+    - `bounce` — ≥1 non-visual-diff, non-cap finding with severity `blocker` or `error`
+    - `escalate` — preview server failed to start, OR axe threw ≥3 consecutive times, OR any required browser binary was absent.
+
+12. Teardown:
     ```bash
     kill $SERVER_PID 2>/dev/null || true
     cd {{repo_root}}
@@ -132,7 +176,7 @@ Respond with exactly one JSON object and nothing else. Finding shape must match
 - required: `severity`, `message`
 - optional: `rule`, `suggestion`, `location`, `attachments`, `metadata`
 
-For a11y findings there is usually no meaningful file/line, so OMIT `location` entirely.
+For a11y findings there is usually no meaningful file/line, so OMIT `location` entirely. For `location`, use an object shape when present — do not emit `location` as a URL string.
 
 ```json
 {
@@ -141,11 +185,11 @@ For a11y findings there is usually no meaningful file/line, so OMIT `location` e
   "findings": [
     {
       "severity": "blocker" | "error" | "warning" | "info",
-      "rule": "a11y.<rule-id>" | "visual-diff",
-      "message": "<description; include the page URL for a11y, route+viewport+diff for visual-diff>",
-      "metadata": { /* per §7/§8 above */ },
+      "rule": "a11y.<rule-id>" | "visual-diff" | "ui-review-cap" | "browser-missing",
+      "message": "<description; include the page URL for a11y, route+viewport+browser for visual-diff>",
+      "metadata": { /* per §8/§9 above */ },
       "attachments": [ /* for visual-diff with status="diff" */
-        { "label": "baseline",  "path": ".cloverleaf/baselines/{slug}-{viewport}.png" },
+        { "label": "baseline",  "path": ".cloverleaf/baselines/{browser}/{slug}-{viewport}.png" },
         { "label": "candidate", "path": ".cloverleaf/runs/{taskId}/ui-review/candidate-{slug}-{viewport}.png" },
         { "label": "diff",      "path": ".cloverleaf/runs/{taskId}/ui-review/diff-{slug}-{viewport}.png" }
       ]
@@ -154,4 +198,4 @@ For a11y findings there is usually no meaningful file/line, so OMIT `location` e
 }
 ```
 
-If verdict is `pass`, `findings` may be empty or include only `warning`/`info`-level findings. If verdict is `escalate`, include a finding explaining what went wrong.
+If verdict is `pass`, `findings` may be empty or include only `warning`/`info`-level findings (including `ui-review-cap` warnings and visual-diff info). If verdict is `escalate`, include a finding explaining what went wrong.

package/skills/cloverleaf-merge/SKILL.md

@@ -71,9 +71,9 @@ description: Human gate for merging a Cloverleaf task. Branches on state — fro
      cloverleaf-cli advance-status <repo_root> ${TASK_ID} escalated agent
      ```
      Exit with a human-readable error explaining the conflict.
-   - Advance task status on main (commits `.cloverleaf/tasks/${TASK_ID}.json` + event):
+   - Advance task status on main (commits `.cloverleaf/tasks/${TASK_ID}.json` + event). The `final-gate → merged` transition is `allowed_actors: [human]` per the task state machine; the skill passes the gate + path as positional args:
      ```bash
-     cloverleaf-cli advance-status <repo_root> ${TASK_ID} merged agent
+     cloverleaf-cli advance-status <repo_root> ${TASK_ID} merged human final_approval_gate full_pipeline
      ```
 
 ### 4. Common: report