@cloverleaf/reference-impl 0.5.1 → 0.5.2

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.2",
   "author": {
     "name": "Renato D'Arrigo",
     "email": "renato.darrigo@gmail.com"

package/README.md

@@ -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}/`.
 - `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.2

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-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-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.2",
   "description": "Reference implementation of the Cloverleaf methodology as Claude Code skills. Implements the Tight Loop (Implementer + Reviewer).",
   "type": "module",
   "license": "MIT",

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

@@ -30,7 +30,7 @@ The rationale: baselines on `{{repo_root}}/.cloverleaf/baselines/` get picked up
   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`, 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.
@@ -75,7 +75,7 @@ The `PLAYWRIGHT_BROWSERS_PATH` environment variable is set to `~/.cache/ms-playw
    - 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`
+     - `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`
@@ -145,7 +145,7 @@ For a11y findings there is usually no meaningful file/line, so OMIT `location` e
       "message": "<description; include the page URL for a11y, route+viewport+diff for visual-diff>",
       "metadata": { /* per §7/§8 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" }
       ]

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