@cloverleaf/reference-impl 0.3.1 → 0.4.1

package/lib/cli.ts

@@ -12,6 +12,8 @@
  *   write-feedback <repoRoot> <taskId> <envelopeJsonPath>
  *   latest-feedback <repoRoot> <taskId>
  *   emit-gate-decision <repoRoot> <workItemId> <gate> <decision> <actor> [--comment=<str>]
+ *   ui-review-config --repo-root <repoRoot>
+ *   plugin-root
  */
 
 import { readFileSync } from 'node:fs';
@@ -25,6 +27,8 @@ import { matchesUiPaths } from './ui-paths.js';
 import { loadUiPathsConfig } from './ui-paths.js';
 import { computeAffectedRoutes } from './affected-routes.js';
 import { loadAffectedRoutesConfig } from './affected-routes.js';
+import { loadUiReviewConfig } from './ui-review-config.js';
+import { getPluginRoot } from './plugin-path.js';
 import type { FeedbackEnvelope } from './feedback.js';
 
 function die(msg: string, code = 1): never {
@@ -43,7 +47,9 @@ function usage(msg?: string): never {
       '  advance-status <repoRoot> <taskId> <toStatus> <actor> [gate] [path]\n' +
       '  write-feedback <repoRoot> <taskId> <envelopeJsonPath>\n' +
       '  latest-feedback <repoRoot> <taskId>\n' +
-      '  emit-gate-decision <repoRoot> <workItemId> <gate> <decision> <actor> [--comment=<str>]\n'
+      '  emit-gate-decision <repoRoot> <workItemId> <gate> <decision> <actor> [--comment=<str>]\n' +
+      '  ui-review-config --repo-root <repoRoot>\n' +
+      '  plugin-root\n'
   );
   process.exit(2);
 }
@@ -221,6 +227,31 @@ try {
       process.exit(0);
     }
 
+    case 'ui-review-config': {
+      const flags = rest.filter((a) => a.startsWith('--'));
+      const repoRootFlag = flags.find((f) => f.startsWith('--repo-root=') || f === '--repo-root');
+      let repoRoot: string | undefined;
+      if (repoRootFlag === '--repo-root') {
+        repoRoot = rest[rest.indexOf('--repo-root') + 1];
+      } else if (repoRootFlag) {
+        repoRoot = repoRootFlag.replace('--repo-root=', '');
+      } else {
+        repoRoot = rest.filter((a) => !a.startsWith('--'))[0];
+      }
+      if (!repoRoot) {
+        console.error('usage: ui-review-config --repo-root <repoRoot>');
+        process.exit(1);
+      }
+      const config = loadUiReviewConfig(repoRoot);
+      process.stdout.write(JSON.stringify(config, null, 2));
+      process.exit(0);
+    }
+
+    case 'plugin-root': {
+      process.stdout.write(getPluginRoot());
+      process.exit(0);
+    }
+
     default:
       usage(`Unknown command: ${command}`);
   }

package/lib/feedback.ts

@@ -13,12 +13,19 @@ export interface FindingLocation {
   work_item_id?: { project: string; id: string };
 }
 
+export interface Attachment {
+  label: string;
+  path: string;
+}
+
 export interface Finding {
   severity: FindingSeverity;
   message: string;
   location?: FindingLocation;
   suggestion?: string;
   rule?: string;
+  attachments?: Attachment[];
+  metadata?: Record<string, unknown>;
 }
 
 export interface FeedbackEnvelope {
@@ -63,7 +70,7 @@ export function latestFeedback(repoRoot: string, taskId: string): FeedbackEnvelo
 export function allFeedback(repoRoot: string, taskId: string): FeedbackEnvelope[] {
   const dir = feedbackDir(repoRoot);
   if (!existsSync(dir)) return [];
-  const re = new RegExp(`^${escapeRegex(taskId)}-r(\\d+)\\.json$`);
+  const re = new RegExp(`^${escapeRegex(taskId)}-[ruq](\\d+)\\.json$`);
   const entries = readdirSync(dir)
     .map((f) => ({ f, m: f.match(re) }))
     .filter((x): x is { f: string; m: RegExpMatchArray } => !!x.m)

package/lib/plugin-path.ts

@@ -0,0 +1,21 @@
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Absolute path to the plugin root.
+ *
+ * At runtime, this module lives at <plugin-root>/lib/plugin-path.js (or .ts in dev),
+ * so the plugin root is the parent directory.
+ *
+ * Works under:
+ * - dev mode (repo source: <repo>/reference-impl/)
+ * - npm install (node_modules/@cloverleaf/reference-impl/)
+ * - claude plugin install cache (~/.claude/plugins/cache/cloverleaf-local/cloverleaf/0.4.1/)
+ * - legacy symlink into ~/.claude/plugins/cloverleaf/
+ * - claude --plugin-dir <path>
+ */
+export function getPluginRoot(): string {
+  return resolve(here, '..');
+}

package/lib/qa-report.ts

@@ -0,0 +1,77 @@
+export interface QaRunResult {
+  ruleId: string;
+  command: string;
+  cwd: string;
+  durationMs: number;
+  passed: boolean;
+  stdoutTail: string;
+  stderrTail: string;
+}
+
+function escape(s: string): string {
+  return s
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+function renderRow(r: QaRunResult): string {
+  const status = r.passed ? 'PASS' : 'FAIL';
+  const statusClass = r.passed ? 'pass' : 'fail';
+  return `
+    <tr class="${statusClass}">
+      <td>${escape(r.ruleId)}</td>
+      <td><code>${escape(r.command)}</code></td>
+      <td>${escape(r.cwd)}</td>
+      <td>${r.durationMs}ms</td>
+      <td class="status">${status}</td>
+    </tr>
+    <tr class="detail ${statusClass}">
+      <td colspan="5">
+        ${r.stdoutTail ? `<details><summary>stdout (tail)</summary><pre>${escape(r.stdoutTail)}</pre></details>` : ''}
+        ${r.stderrTail ? `<details open><summary>stderr (tail)</summary><pre>${escape(r.stderrTail)}</pre></details>` : ''}
+      </td>
+    </tr>
+  `;
+}
+
+export function renderQaReport(runs: QaRunResult[]): string {
+  const empty = runs.length === 0
+    ? `<p class="empty">No runs / results.</p>`
+    : '';
+  const rows = runs.map(renderRow).join('');
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>Cloverleaf QA Report</title>
+  <style>
+    body { font: 14px/1.4 system-ui, sans-serif; margin: 2rem; color: #111; }
+    table { width: 100%; border-collapse: collapse; }
+    th, td { padding: 0.5rem; border-bottom: 1px solid #ddd; text-align: left; vertical-align: top; }
+    .status { font-weight: 600; }
+    .pass .status { color: #0a7; }
+    .fail .status { color: #c33; }
+    tr.detail td { background: #fafafa; padding-top: 0; }
+    pre { overflow: auto; background: #f4f4f4; padding: 0.5rem; }
+    .empty { color: #888; }
+  </style>
+</head>
+<body>
+  <h1>Cloverleaf QA Report</h1>
+  ${empty}
+  ${runs.length > 0 ? `
+  <table>
+    <thead>
+      <tr><th>Rule</th><th>Command</th><th>CWD</th><th>Duration</th><th>Status</th></tr>
+    </thead>
+    <tbody>
+      ${rows}
+    </tbody>
+  </table>
+  ` : ''}
+</body>
+</html>`;
+}

package/lib/qa-rules.ts

@@ -12,7 +12,7 @@ export interface QaRule {
   command: string;
 }
 
-export function loadDefaultRules(): QaRule[] {
+function loadDefaultRules(): QaRule[] {
   if (!existsSync(DEFAULT_CONFIG)) return [];
   const doc = JSON.parse(readFileSync(DEFAULT_CONFIG, 'utf-8')) as { rules?: QaRule[] };
   return Array.isArray(doc.rules) ? doc.rules : [];

package/lib/route-slug.ts

@@ -0,0 +1,21 @@
+/**
+ * Turn a URL path into a filesystem-safe slug used in baseline/diff filenames.
+ * - "/" → "index"
+ * - "/faq/" → "faq"
+ * - "/guide/chapter-3/" → "guide-chapter-3"
+ * - "/docs/v1.2/getting started/" → "docs-v1-2-getting-started"
+ * Query/hash are stripped.
+ */
+export function slugifyRoute(route: string): string {
+  const pathOnly = route.split(/[?#]/)[0];
+  if (pathOnly === '/' || pathOnly === '') return 'index';
+  const trimmed = pathOnly.replace(/^\/+|\/+$/g, '');
+  if (trimmed === '') return 'index';
+  const slugged = trimmed
+    .toLowerCase()
+    .replace(/[^a-z0-9/-]+/g, '-')
+    .replace(/\/+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '');
+  return slugged || 'index';
+}

package/lib/ui-paths.ts

@@ -5,7 +5,7 @@ import { dirname, join } from 'node:path';
 const here = dirname(fileURLToPath(import.meta.url));
 const DEFAULT_CONFIG = join(here, '..', 'config', 'ui-paths.json');
 
-export function loadDefaultPatterns(): string[] {
+function loadDefaultPatterns(): string[] {
   if (!existsSync(DEFAULT_CONFIG)) return ['site/**'];
   const doc = JSON.parse(readFileSync(DEFAULT_CONFIG, 'utf-8')) as { patterns?: string[] };
   return Array.isArray(doc.patterns) ? doc.patterns : ['site/**'];

package/lib/ui-review-config.ts

@@ -0,0 +1,62 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const PACKAGE_DEFAULT = join(here, '..', 'config', 'ui-review.json');
+
+export interface Viewport {
+  width: number;
+  height: number;
+}
+
+export interface UiReviewConfig {
+  viewports: Record<string, Viewport>;
+  visualDiff: {
+    enabled: boolean;
+    threshold: number;
+    maxDiffRatio: number;
+    mask: string[];
+  };
+  axe: {
+    viewports: string[];
+    dedupeBy: ('ruleId' | 'target')[];
+    ignored: Array<{ ruleId: string; target: string }>;
+  };
+}
+
+const HARDCODED_FALLBACK: UiReviewConfig = {
+  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: [] },
+};
+
+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)) {
+      (doc.axe as UiReviewConfig['axe']).ignored = [];
+    }
+    return doc;
+  } catch {
+    return null;
+  }
+}
+
+export function loadUiReviewConfig(repoRoot: string): UiReviewConfig {
+  const consumerPath = join(repoRoot, '.cloverleaf', 'config', 'ui-review.json');
+  if (existsSync(consumerPath)) {
+    const parsed = readAsConfig(consumerPath);
+    if (parsed) return parsed;
+  }
+  if (existsSync(PACKAGE_DEFAULT)) {
+    const parsed = readAsConfig(PACKAGE_DEFAULT);
+    if (parsed) return parsed;
+  }
+  return HARDCODED_FALLBACK;
+}

package/lib/visual-diff.ts

@@ -0,0 +1,97 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import pixelmatch from 'pixelmatch';
+import { PNG } from 'pngjs';
+
+export type VisualDiffStatus = 'new-baseline' | 'match' | 'diff' | 'dimension-mismatch';
+
+export interface VisualDiffResult {
+  status: VisualDiffStatus;
+  diffPixels: number;
+  diffRatio: number;
+  width: number;
+  height: number;
+}
+
+export interface CompareVisualArgs {
+  baselinePath: string;
+  candidateBuf: Buffer;
+  diffPath: string;
+  candidateOutPath: string;
+  threshold: number;
+  maxDiffRatio: number;
+}
+
+function ensureDir(path: string): void {
+  mkdirSync(dirname(path), { recursive: true });
+}
+
+function writeBaseline(baselinePath: string, buf: Buffer): void {
+  ensureDir(baselinePath);
+  writeFileSync(baselinePath, buf);
+}
+
+export function compareVisual(args: CompareVisualArgs): VisualDiffResult {
+  const candidatePng = PNG.sync.read(args.candidateBuf);
+
+  if (!existsSync(args.baselinePath)) {
+    writeBaseline(args.baselinePath, args.candidateBuf);
+    return {
+      status: 'new-baseline',
+      diffPixels: 0,
+      diffRatio: 0,
+      width: candidatePng.width,
+      height: candidatePng.height,
+    };
+  }
+
+  const baselineBuf = readFileSync(args.baselinePath);
+  const baselinePng = PNG.sync.read(baselineBuf);
+
+  if (baselinePng.width !== candidatePng.width || baselinePng.height !== candidatePng.height) {
+    writeBaseline(args.baselinePath, args.candidateBuf);
+    return {
+      status: 'dimension-mismatch',
+      diffPixels: 0,
+      diffRatio: 0,
+      width: candidatePng.width,
+      height: candidatePng.height,
+    };
+  }
+
+  const diffPng = new PNG({ width: candidatePng.width, height: candidatePng.height });
+  const diffPixels = pixelmatch(
+    baselinePng.data,
+    candidatePng.data,
+    diffPng.data,
+    candidatePng.width,
+    candidatePng.height,
+    { threshold: args.threshold },
+  );
+  const totalPixels = candidatePng.width * candidatePng.height;
+  const diffRatio = diffPixels / totalPixels;
+
+  if (diffRatio > args.maxDiffRatio) {
+    ensureDir(args.diffPath);
+    writeFileSync(args.diffPath, PNG.sync.write(diffPng));
+    ensureDir(args.candidateOutPath);
+    writeFileSync(args.candidateOutPath, args.candidateBuf);
+    writeBaseline(args.baselinePath, args.candidateBuf);
+    return {
+      status: 'diff',
+      diffPixels,
+      diffRatio,
+      width: candidatePng.width,
+      height: candidatePng.height,
+    };
+  }
+
+  writeBaseline(args.baselinePath, args.candidateBuf);
+  return {
+    status: 'match',
+    diffPixels,
+    diffRatio,
+    width: candidatePng.width,
+    height: candidatePng.height,
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloverleaf/reference-impl",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "Reference implementation of the Cloverleaf methodology as Claude Code skills. Implements the Tight Loop (Implementer + Reviewer).",
   "type": "module",
   "license": "MIT",
@@ -23,6 +23,7 @@
     "reference-implementation"
   ],
   "files": [
+    ".claude-plugin",
     "skills",
     "lib",
     "prompts",
@@ -46,14 +47,18 @@
     "prepublishOnly": "npm test && npm run build"
   },
   "dependencies": {
-    "@cloverleaf/standard": "^0.3.0",
+    "@cloverleaf/standard": "^0.4.0",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
+    "axe-core": "^4.10.0",
+    "pixelmatch": "^5.3.0",
     "playwright": "^1.47.0",
-    "axe-core": "^4.10.0"
+    "pngjs": "^7.0.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
+    "@types/pixelmatch": "^5.2.6",
+    "@types/pngjs": "^6.0.5",
     "tsx": "^4.19.0",
     "typescript": "^5.5.0",
     "vitest": "^2.0.0"

package/prompts/qa.md

@@ -57,6 +57,27 @@ The Standard's QA contract requires a `preview_uri`. You were passed the sentine
 - Use `git worktree`: do NOT `git checkout` in the main working directory.
 - Always teardown the worktree, even on error.
 
+## QA Report (v0.4)
+
+After executing all matched QA rules, write an HTML report summarizing each run to `<repoRoot>/.cloverleaf/runs/{taskId}/qa/report.html` (substitute `{taskId}` with the `id` field from the task input, e.g., `{{task.id}}`).
+
+Use `renderQaReport(runs)` from `lib/qa-report.ts` to produce the HTML. Ensure the directory exists first (`mkdir -p`).
+
+In the feedback you emit, include the report as an attachment on a single info-level finding (or on whichever summary finding you already emit):
+
+```json
+{
+  "severity": "info",
+  "rule": "qa-report",
+  "message": "QA report written",
+  "attachments": [
+    { "label": "report", "path": ".cloverleaf/runs/{taskId}/qa/report.html" }
+  ]
+}
+```
+
+This lets humans at final-gate inspect the full QA detail without grovelling through logs.
+
 ## Output
 
 Respond with exactly one JSON object and nothing else:

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 for accessibility violations using axe-core in a headless Playwright chromium browser. You are read-only — you do not modify source code or tests.
+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.
 
 ## Input
 
@@ -11,20 +11,35 @@ You are the Cloverleaf UI Reviewer. Your job: review a task's UI changes for acc
 - **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.
 
-## Scope (v0.3)
+## Paths
 
-- Accessibility only (axe-core). No visual diff, no responsive checks.
-- Single viewport: 1280×800.
-- Run axe ONLY on the pages listed in `{{affected_routes}}`.
-  - If `{{affected_routes}}` is `"all"`: crawl up to 20 pages reachable from `/` via same-origin link discovery (v0.2 fallback behavior).
-  - If `{{affected_routes}}` is `[]`: return `verdict: "pass"` with summary "No renderable routes affected, skipping axe." Do NOT start the preview server.
-  - Otherwise: visit exactly the URLs listed. No link-discovery crawl.
-- Visual diff, viewports loop, and `visual_diff_uri` are deferred to v0.4.
+You operate in two filesystem locations — keep them straight:
+
+- `<worktree>` — the ephemeral worktree at `$TMPDIR` (set up in step 2 of the Runtime procedure). You run the dev server here and execute Playwright here.
+- `<repoRoot>` — the main repository root at `{{repo_root}}` (always an absolute path). This is the ONLY location where baselines, diff PNGs, candidate PNGs, and artifacts are written.
+
+**All `compareVisual` paths MUST be rooted at `{{repo_root}}`, NOT at `$TMPDIR`.**
+
+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)
+
+- **Accessibility (axe-core):** run at the viewports listed in `{{ui_review_config}}.axe.viewports`.
+  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 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).
+  - otherwise → visit exactly the URLs listed.
 
 ## Playwright cache
 
-The `PLAYWRIGHT_BROWSERS_PATH` environment variable is set to `~/.cache/ms-playwright` before you are invoked. Playwright resolves chromium from this shared cache, so `npm ci` in the worktree does NOT re-download ~300 MB of browser binaries. 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. If the browser is missing, return `verdict: "escalate"` with a synthetic finding: `"Playwright chromium not installed. Run 'npx playwright install chromium' on this machine."`
 
 ## Runtime procedure
 
@@ -36,7 +51,7 @@ The `PLAYWRIGHT_BROWSERS_PATH` environment variable is set to `~/.cache/ms-playw
    git worktree add "$TMPDIR" {{branch}}
    ```
 
-3. For this repo, UI lives in `site/`. Install dependencies and start the dev server:
+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:
    ```bash
    cd "$TMPDIR/site"
    npm ci
@@ -47,47 +62,77 @@ The `PLAYWRIGHT_BROWSERS_PATH` environment variable is set to `~/.cache/ms-playw
 4. Wait up to 30s for `http://localhost:{{preview_port}}/` to respond 200. If the server fails to start in 30s, kill it and return verdict `escalate`.
 
 5. Determine the site base path:
-   1. Check `<repoRoot>/.cloverleaf/config/astro-base.json`. Expected shape: `{ "base": "<path>" }`. If present, use the `base` field verbatim and skip to step 6. (Consumer override — checked before parsing astro config.)
-   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`). This is best-effort; the v0.3 behavior is preserved. Consumers with non-conventional layouts should supply `astro-base.json` rather than relying on parse.
+   1. Check `{{repo_root}}/.cloverleaf/config/astro-base.json`. Expected shape: `{ "base": "<path>" }`. If present, use the `base` field verbatim and skip to step 6. (Consumer override — checked before parsing astro config.)
+   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. For each route in `{{affected_routes}}` (or the crawl set, if `"all"`):
-   - Construct URL `http://localhost:{{preview_port}}<base><route>`.
-   - Navigate. If 404, retry at `http://localhost:{{preview_port}}<route>` (without base).
-   - Inject and run axe-core:
-     ```javascript
-     import axe from 'axe-core';
-     const results = await axe.run(document);
-     ```
-   - Collect violations.
-
-7. Map violations to findings:
+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"`
 
-8. Compute verdict:
-   - `pass` — zero findings with severity `blocker` or `error`
-   - `bounce` — ≥1 finding with severity `blocker` or `error`
-   - `escalate` — preview server failed to start, OR axe threw ≥3 consecutive times, OR Playwright chromium missing.
+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.
 
-9. Teardown:
-   ```bash
-   kill $SERVER_PID 2>/dev/null || true
-   cd {{repo_root}}
-   git worktree remove --force "$TMPDIR"
-   ```
+11. Teardown:
+    ```bash
+    kill $SERVER_PID 2>/dev/null || true
+    cd {{repo_root}}
+    git worktree remove --force "$TMPDIR"
+    ```
 
 ## Tool constraints
 
-- Read-only: do NOT edit source files.
+- Read-only for source files and tests.
+- You MAY write under `{{repo_root}}/.cloverleaf/baselines/` and `{{repo_root}}/.cloverleaf/runs/{taskId}/ui-review/` on the feature branch — these are the baselines and artifacts.
 - Use `git worktree`: do NOT `git checkout` in the main working directory.
 - Always teardown the server and worktree, even on error.
 
 ## Output
 
-Respond with exactly one JSON object and nothing else. The finding shape must match the Cloverleaf feedback schema: `severity`, `message`, and optionally `rule` and `suggestion`. The `location` field is defined by the schema as an OBJECT with `{file, line?, work_item_id?}` — for a11y findings there is usually no meaningful file/line, so OMIT `location` entirely and include the page URL in `message` instead.
+Respond with exactly one JSON object and nothing else. Finding shape must match the Cloverleaf 0.4.0 feedback schema:
+- required: `severity`, `message`
+- optional: `rule`, `suggestion`, `location`, `attachments`, `metadata`
+
+For a11y findings there is usually no meaningful file/line, so OMIT `location` entirely.
 
 ```json
 {
@@ -96,11 +141,17 @@ Respond with exactly one JSON object and nothing else. The finding shape must ma
   "findings": [
     {
       "severity": "blocker" | "error" | "warning" | "info",
-      "rule": "a11y.<rule-id>",
-      "message": "<rule description — include the page URL (e.g., 'at /guide/') in the message>"
+      "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 */ },
+      "attachments": [ /* for visual-diff with status="diff" */
+        { "label": "baseline",  "path": ".cloverleaf/baselines/{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" }
+      ]
     }
   ]
 }
 ```
 
-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 (even if synthetic).
+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.