@cloverleaf/reference-impl 0.2.0 → 0.3.1

package/README.md

@@ -15,7 +15,7 @@ npm install            # pulls @cloverleaf/standard + deps
 ./install.sh --project # local install into ./.claude/plugins/cloverleaf/
 ```
 
-## Scope (v0.2)
+## Scope (v0.3)
 
 v0.2 implements both paths of the Delivery track:
 
@@ -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.2) | Playwright + axe-core, single viewport, a11y only |
+| UI Reviewer | Real (v0.3) | Playwright + axe-core, diff-scoped to affected routes, single viewport, a11y only |
 | QA | Real (v0.2) | Per-package test runner via `git worktree` |
 | Plan | Stub | Deferred to v0.3 |
 | Researcher | Stub | Deferred to v0.3 |
@@ -52,13 +52,52 @@ Two JSON config files in `config/` (overridable per consumer project):
 - `config/ui-paths.json` — glob patterns that trigger UI Reviewer (default: `site/**`)
 - `config/qa-rules.json` — per-package test commands
 
+### Customizing for your repo
+
+The package ships with cloverleaf-flavored defaults in `config/`. Your repo overrides any of them by placing a file of the same name at `<repoRoot>/.cloverleaf/config/<name>.json`. Consumer override is a **full replacement** — your file becomes the complete source of truth for that config.
+
+Available overrides:
+
+| Override file | Purpose |
+|---|---|
+| `.cloverleaf/config/ui-paths.json` | Controls `detect-ui-paths` — which diffs trigger the `ui-review` state |
+| `.cloverleaf/config/qa-rules.json` | Per-package test commands for the QA agent |
+| `.cloverleaf/config/affected-routes.json` | Rules for mapping diffs to site routes (UI Reviewer scope); includes `contentRoutes` for content-collection mapping |
+| `.cloverleaf/config/astro-base.json` | Explicit Astro `base` path — avoids best-effort parsing of `astro.config.*` |
+
+Example `affected-routes.json` override for a Next.js project:
+
+```json
+{
+  "pageRoots": ["apps/web/app/"],
+  "globalPatterns": ["apps/web/components/**", "apps/web/styles/**"],
+  "routeScope": ["apps/web/**"],
+  "contentRoutes": {}
+}
+```
+
+Example `astro-base.json`:
+
+```json
+{ "base": "/my-docs" }
+```
+
+All overrides are read fresh on every skill invocation; no caching. Edit and the next `/cloverleaf-run` picks it up.
+
 ### Known limitations
 
-- Playwright installs ~300MB into each `git worktree` (v0.3 will cache).
 - Concurrent `/cloverleaf-run` on the same repo may race on preview ports.
-- UI Reviewer visual diff + multi-viewport deferred to v0.3.
+- 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:
+
+    npx playwright install chromium
+
+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.
+
 ## Quick start — toy repo
 
 ```bash

package/VERSION

@@ -1 +1 @@
-0.2.0
+0.3.1

package/config/affected-routes.json

@@ -0,0 +1,13 @@
+{
+  "pageRoots": ["site/src/pages/"],
+  "globalPatterns": [
+    "site/src/layouts/**",
+    "site/src/components/**",
+    "site/src/styles/**",
+    "site/public/**",
+    "site/astro.config.*",
+    "site/src/content/**"
+  ],
+  "routeScope": ["site/src/**", "site/public/**"],
+  "contentRoutes": {}
+}

package/dist/affected-routes.mjs

@@ -0,0 +1,99 @@
+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 DEFAULT_CONFIG = join(here, '..', 'config', 'affected-routes.json');
+function globToRegex(pattern) {
+    const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+    const regex = escaped
+        .replace(/\*\*/g, '\u0000')
+        .replace(/\*/g, '[^/]*')
+        .replace(/\u0000/g, '.*');
+    return new RegExp(`^${regex}$`);
+}
+function matchesAny(file, patterns) {
+    return patterns.some((p) => globToRegex(p).test(file));
+}
+function routeForPage(file, pageRoot) {
+    if (!file.startsWith(pageRoot))
+        return null;
+    const rel = file.slice(pageRoot.length);
+    const withoutExt = rel.replace(/\.(astro|mdx)$/, '');
+    if (!withoutExt || withoutExt === rel)
+        return null;
+    if (withoutExt === 'index')
+        return '/';
+    return `/${withoutExt}/`;
+}
+export function loadDefaultConfig() {
+    if (!existsSync(DEFAULT_CONFIG)) {
+        throw new Error(`affected-routes config not found at ${DEFAULT_CONFIG}`);
+    }
+    const doc = JSON.parse(readFileSync(DEFAULT_CONFIG, 'utf-8'));
+    return {
+        pageRoots: Array.isArray(doc.pageRoots) ? doc.pageRoots : [],
+        globalPatterns: Array.isArray(doc.globalPatterns) ? doc.globalPatterns : [],
+        routeScope: Array.isArray(doc.routeScope) ? doc.routeScope : [],
+        contentRoutes: (doc.contentRoutes && typeof doc.contentRoutes === 'object' && !Array.isArray(doc.contentRoutes))
+            ? doc.contentRoutes
+            : {},
+    };
+}
+export function loadAffectedRoutesConfig(repoRoot) {
+    const consumerPath = join(repoRoot, '.cloverleaf', 'config', 'affected-routes.json');
+    if (existsSync(consumerPath)) {
+        try {
+            const doc = JSON.parse(readFileSync(consumerPath, 'utf-8'));
+            return {
+                pageRoots: Array.isArray(doc.pageRoots) ? doc.pageRoots : [],
+                globalPatterns: Array.isArray(doc.globalPatterns) ? doc.globalPatterns : [],
+                routeScope: Array.isArray(doc.routeScope) ? doc.routeScope : [],
+                contentRoutes: (doc.contentRoutes && typeof doc.contentRoutes === 'object' && !Array.isArray(doc.contentRoutes))
+                    ? doc.contentRoutes
+                    : {},
+            };
+        }
+        catch {
+            // fall through
+        }
+    }
+    return loadDefaultConfig();
+}
+export function computeAffectedRoutes(changedFiles, config) {
+    const routes = new Set();
+    let inScopeButUnmatched = false;
+    for (const file of changedFiles) {
+        if (matchesAny(file, config.globalPatterns)) {
+            return 'all';
+        }
+        let mapped = null;
+        for (const root of config.pageRoots) {
+            const r = routeForPage(file, root);
+            if (r) {
+                mapped = r;
+                break;
+            }
+        }
+        if (mapped) {
+            routes.add(mapped);
+            continue;
+        }
+        // contentRoutes: map content-collection files to specific routes
+        for (const [pattern, route] of Object.entries(config.contentRoutes)) {
+            if (globToRegex(pattern).test(file)) {
+                routes.add(route);
+                mapped = route;
+                break;
+            }
+        }
+        if (mapped)
+            continue;
+        if (matchesAny(file, config.routeScope)) {
+            inScopeButUnmatched = true;
+        }
+    }
+    if (inScopeButUnmatched) {
+        return 'all';
+    }
+    return Array.from(routes).sort();
+}

package/dist/cli.mjs

@@ -20,7 +20,10 @@ import { advanceStatus } from './state.mjs';
 import { emitGateDecision } from './events.mjs';
 import { writeFeedback, latestFeedback } from './feedback.mjs';
 import { nextTaskId, inferProject } from './ids.mjs';
-import { matchesUiPaths, loadDefaultPatterns } from './ui-paths.mjs';
+import { matchesUiPaths } from './ui-paths.mjs';
+import { loadUiPathsConfig } from './ui-paths.mjs';
+import { computeAffectedRoutes } from './affected-routes.mjs';
+import { loadAffectedRoutesConfig } from './affected-routes.mjs';
 function die(msg, code = 1) {
     process.stderr.write(msg + '\n');
     process.exit(code);
@@ -176,11 +179,38 @@ try {
                 console.error(`branch ${branch} not found: ${stderrStr || err.message || 'unknown'}`);
                 process.exit(2);
             }
-            const patterns = loadDefaultPatterns();
+            const { patterns } = loadUiPathsConfig(repoRoot);
             const result = matchesUiPaths(changed, patterns);
             process.stdout.write(`${result}\n`);
             process.exit(0);
         }
+        case 'affected-routes': {
+            const [repoRoot, taskId] = rest;
+            if (!repoRoot || !taskId) {
+                console.error('usage: affected-routes <repo_root> <task-id>');
+                process.exit(1);
+            }
+            const branch = `cloverleaf/${taskId}`;
+            let changed;
+            try {
+                const out = execSync(`git diff --name-only main..${branch}`, {
+                    cwd: repoRoot,
+                    encoding: 'utf-8',
+                    stdio: ['pipe', 'pipe', 'pipe'],
+                });
+                changed = out.split('\n').map((l) => l.trim()).filter(Boolean);
+            }
+            catch (e) {
+                const err = e;
+                const stderrStr = typeof err.stderr === 'string' ? err.stderr : err.stderr?.toString() ?? '';
+                console.error(`branch ${branch} not found: ${stderrStr || err.message || 'unknown'}`);
+                process.exit(2);
+            }
+            const config = loadAffectedRoutesConfig(repoRoot);
+            const result = computeAffectedRoutes(changed, config);
+            process.stdout.write(`${JSON.stringify(result)}\n`);
+            process.exit(0);
+        }
         default:
             usage(`Unknown command: ${command}`);
     }

package/dist/qa-rules.mjs

@@ -10,6 +10,21 @@ export function loadDefaultRules() {
     const doc = JSON.parse(readFileSync(DEFAULT_CONFIG, 'utf-8'));
     return Array.isArray(doc.rules) ? doc.rules : [];
 }
+export function loadQaRulesConfig(repoRoot) {
+    const consumerPath = join(repoRoot, '.cloverleaf', 'config', 'qa-rules.json');
+    if (existsSync(consumerPath)) {
+        try {
+            const doc = JSON.parse(readFileSync(consumerPath, 'utf-8'));
+            if (Array.isArray(doc.rules)) {
+                return doc.rules;
+            }
+        }
+        catch {
+            // fall through
+        }
+    }
+    return loadDefaultRules();
+}
 export function selectTestCommands(changedFiles, rules) {
     return rules.filter((rule) => matchesUiPaths(changedFiles, rule.match));
 }

package/dist/ui-paths.mjs

@@ -17,6 +17,21 @@ function globToRegex(pattern) {
         .replace(/\u0000/g, '.*');
     return new RegExp(`^${regex}$`);
 }
+export function loadUiPathsConfig(repoRoot) {
+    const consumerPath = join(repoRoot, '.cloverleaf', 'config', 'ui-paths.json');
+    if (existsSync(consumerPath)) {
+        try {
+            const doc = JSON.parse(readFileSync(consumerPath, 'utf-8'));
+            if (Array.isArray(doc.patterns)) {
+                return { patterns: doc.patterns };
+            }
+        }
+        catch {
+            // fall through to package default
+        }
+    }
+    return { patterns: loadDefaultPatterns() };
+}
 export function matchesUiPaths(changedFiles, patterns) {
     if (changedFiles.length === 0)
         return false;

package/install.sh

@@ -55,3 +55,10 @@ echo "Skills available: $(ls "${INSTALL_ROOT}/skills" | wc -l | tr -d ' ')"
 echo ""
 echo "Add ${INSTALL_ROOT}/bin to your PATH if you want to invoke cloverleaf-cli directly,"
 echo "or reference it by absolute path from your skill calls."
+
+# 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
+  echo ""
+  echo "Note: UI Reviewer uses Playwright chromium. If you plan to run /cloverleaf-ui-review, install once with:"
+  echo "  npx playwright install chromium"
+fi

package/lib/affected-routes.ts

@@ -0,0 +1,113 @@
+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 DEFAULT_CONFIG = join(here, '..', 'config', 'affected-routes.json');
+
+export interface AffectedRoutesConfig {
+  pageRoots: string[];
+  globalPatterns: string[];
+  routeScope: string[];
+  contentRoutes: Record<string, string>;
+}
+
+function globToRegex(pattern: string): RegExp {
+  const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+  const regex = escaped
+    .replace(/\*\*/g, '\u0000')
+    .replace(/\*/g, '[^/]*')
+    .replace(/\u0000/g, '.*');
+  return new RegExp(`^${regex}$`);
+}
+
+function matchesAny(file: string, patterns: string[]): boolean {
+  return patterns.some((p) => globToRegex(p).test(file));
+}
+
+function routeForPage(file: string, pageRoot: string): string | null {
+  if (!file.startsWith(pageRoot)) return null;
+  const rel = file.slice(pageRoot.length);
+  const withoutExt = rel.replace(/\.(astro|mdx)$/, '');
+  if (!withoutExt || withoutExt === rel) return null;
+  if (withoutExt === 'index') return '/';
+  return `/${withoutExt}/`;
+}
+
+export function loadDefaultConfig(): AffectedRoutesConfig {
+  if (!existsSync(DEFAULT_CONFIG)) {
+    throw new Error(`affected-routes config not found at ${DEFAULT_CONFIG}`);
+  }
+  const doc = JSON.parse(readFileSync(DEFAULT_CONFIG, 'utf-8')) as Partial<AffectedRoutesConfig>;
+  return {
+    pageRoots: Array.isArray(doc.pageRoots) ? doc.pageRoots : [],
+    globalPatterns: Array.isArray(doc.globalPatterns) ? doc.globalPatterns : [],
+    routeScope: Array.isArray(doc.routeScope) ? doc.routeScope : [],
+    contentRoutes: (doc.contentRoutes && typeof doc.contentRoutes === 'object' && !Array.isArray(doc.contentRoutes))
+      ? doc.contentRoutes
+      : {},
+  };
+}
+
+export function loadAffectedRoutesConfig(repoRoot: string): AffectedRoutesConfig {
+  const consumerPath = join(repoRoot, '.cloverleaf', 'config', 'affected-routes.json');
+  if (existsSync(consumerPath)) {
+    try {
+      const doc = JSON.parse(readFileSync(consumerPath, 'utf-8')) as Partial<AffectedRoutesConfig>;
+      return {
+        pageRoots: Array.isArray(doc.pageRoots) ? doc.pageRoots : [],
+        globalPatterns: Array.isArray(doc.globalPatterns) ? doc.globalPatterns : [],
+        routeScope: Array.isArray(doc.routeScope) ? doc.routeScope : [],
+        contentRoutes: (doc.contentRoutes && typeof doc.contentRoutes === 'object' && !Array.isArray(doc.contentRoutes))
+          ? doc.contentRoutes
+          : {},
+      };
+    } catch {
+      // fall through
+    }
+  }
+  return loadDefaultConfig();
+}
+
+export function computeAffectedRoutes(
+  changedFiles: string[],
+  config: AffectedRoutesConfig
+): string[] | 'all' {
+  const routes = new Set<string>();
+  let inScopeButUnmatched = false;
+
+  for (const file of changedFiles) {
+    if (matchesAny(file, config.globalPatterns)) {
+      return 'all';
+    }
+    let mapped: string | null = null;
+    for (const root of config.pageRoots) {
+      const r = routeForPage(file, root);
+      if (r) {
+        mapped = r;
+        break;
+      }
+    }
+    if (mapped) {
+      routes.add(mapped);
+      continue;
+    }
+    // contentRoutes: map content-collection files to specific routes
+    for (const [pattern, route] of Object.entries(config.contentRoutes)) {
+      if (globToRegex(pattern).test(file)) {
+        routes.add(route);
+        mapped = route;
+        break;
+      }
+    }
+    if (mapped) continue;
+    if (matchesAny(file, config.routeScope)) {
+      inScopeButUnmatched = true;
+    }
+  }
+
+  if (inScopeButUnmatched) {
+    return 'all';
+  }
+  return Array.from(routes).sort();
+}

package/lib/cli.ts

@@ -21,7 +21,10 @@ import { advanceStatus } from './state.js';
 import { emitGateDecision } from './events.js';
 import { writeFeedback, latestFeedback } from './feedback.js';
 import { nextTaskId, inferProject } from './ids.js';
-import { matchesUiPaths, loadDefaultPatterns } from './ui-paths.js';
+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 type { FeedbackEnvelope } from './feedback.js';
 
 function die(msg: string, code = 1): never {
@@ -185,12 +188,39 @@ try {
         console.error(`branch ${branch} not found: ${stderrStr || err.message || 'unknown'}`);
         process.exit(2);
       }
-      const patterns = loadDefaultPatterns();
+      const { patterns } = loadUiPathsConfig(repoRoot);
       const result = matchesUiPaths(changed, patterns);
       process.stdout.write(`${result}\n`);
       process.exit(0);
     }
 
+    case 'affected-routes': {
+      const [repoRoot, taskId] = rest;
+      if (!repoRoot || !taskId) {
+        console.error('usage: affected-routes <repo_root> <task-id>');
+        process.exit(1);
+      }
+      const branch = `cloverleaf/${taskId}`;
+      let changed: string[];
+      try {
+        const out = execSync(`git diff --name-only main..${branch}`, {
+          cwd: repoRoot,
+          encoding: 'utf-8',
+          stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        changed = out.split('\n').map((l) => l.trim()).filter(Boolean);
+      } catch (e: unknown) {
+        const err = e as { stderr?: Buffer | string; message?: string };
+        const stderrStr = typeof err.stderr === 'string' ? err.stderr : err.stderr?.toString() ?? '';
+        console.error(`branch ${branch} not found: ${stderrStr || err.message || 'unknown'}`);
+        process.exit(2);
+      }
+      const config = loadAffectedRoutesConfig(repoRoot);
+      const result = computeAffectedRoutes(changed, config);
+      process.stdout.write(`${JSON.stringify(result)}\n`);
+      process.exit(0);
+    }
+
     default:
       usage(`Unknown command: ${command}`);
   }

package/lib/qa-rules.ts

@@ -18,6 +18,21 @@ export function loadDefaultRules(): QaRule[] {
   return Array.isArray(doc.rules) ? doc.rules : [];
 }
 
+export function loadQaRulesConfig(repoRoot: string): QaRule[] {
+  const consumerPath = join(repoRoot, '.cloverleaf', 'config', 'qa-rules.json');
+  if (existsSync(consumerPath)) {
+    try {
+      const doc = JSON.parse(readFileSync(consumerPath, 'utf-8')) as { rules?: QaRule[] };
+      if (Array.isArray(doc.rules)) {
+        return doc.rules;
+      }
+    } catch {
+      // fall through
+    }
+  }
+  return loadDefaultRules();
+}
+
 export function selectTestCommands(changedFiles: string[], rules: QaRule[]): QaRule[] {
   return rules.filter((rule) => matchesUiPaths(changedFiles, rule.match));
 }

package/lib/ui-paths.ts

@@ -20,6 +20,21 @@ function globToRegex(pattern: string): RegExp {
   return new RegExp(`^${regex}$`);
 }
 
+export function loadUiPathsConfig(repoRoot: string): { patterns: string[] } {
+  const consumerPath = join(repoRoot, '.cloverleaf', 'config', 'ui-paths.json');
+  if (existsSync(consumerPath)) {
+    try {
+      const doc = JSON.parse(readFileSync(consumerPath, 'utf-8')) as { patterns?: string[] };
+      if (Array.isArray(doc.patterns)) {
+        return { patterns: doc.patterns };
+      }
+    } catch {
+      // fall through to package default
+    }
+  }
+  return { patterns: loadDefaultPatterns() };
+}
+
 export function matchesUiPaths(changedFiles: string[], patterns: string[]): boolean {
   if (changedFiles.length === 0) return false;
   const regexes = patterns.map(globToRegex);

package/package.json

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

package/prompts/ui-reviewer.md

@@ -10,23 +10,33 @@ You are the Cloverleaf UI Reviewer. Your job: review a task's UI changes for acc
 - **Repo root**: {{repo_root}}
 - **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 `[]`
 
-## Scope (v0.2)
+## Scope (v0.3)
 
 - Accessibility only (axe-core). No visual diff, no responsive checks.
 - Single viewport: 1280×800.
-- Up to 20 pages reachable from `/` via same-origin link discovery.
-- Visual diff, viewports loop, and `visual_diff_uri` are deferred to v0.3.
+- 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.
+
+## 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."`
 
 ## Runtime procedure
 
-1. Set up an isolated worktree of the feature branch:
+1. If `{{affected_routes}}` is `[]`, return immediately (pass-skip) — no worktree, no server, no browser.
+
+2. Set up an isolated worktree of the feature branch:
    ```bash
    TMPDIR=$(mktemp -d)
    git worktree add "$TMPDIR" {{branch}}
    ```
 
-2. For this repo, UI lives in `site/`. Install dependencies and start the dev server:
+3. For this repo, UI lives in `site/`. Install dependencies and start the dev server:
    ```bash
    cd "$TMPDIR/site"
    npm ci
@@ -34,32 +44,35 @@ You are the Cloverleaf UI Reviewer. Your job: review a task's UI changes for acc
    SERVER_PID=$!
    ```
 
-3. 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`.
+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.
+   3. If both fail, treat base as empty string.
 
-4. Use Playwright chromium (headless) to:
-   - Navigate to `/`
-   - Discover same-origin links (collect `<a href>` values pointing to the same origin)
-   - Visit up to 20 distinct pages (including `/`)
-   - On each page, inject and run `axe-core`:
+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 all violations
+   - Collect violations.
 
-5. Map violations to findings:
+7. Map violations to findings:
    - axe `impact: "critical"` → `severity: "blocker"`
    - axe `impact: "serious"` → `severity: "error"`
    - axe `impact: "moderate"` → `severity: "warning"`
    - axe `impact: "minor"` → `severity: "info"`
-   - Each finding: `{severity, rule: "a11y.<wcag-id-or-rule-id>", message: <axe description>, location: <page url>}`
 
-6. Compute verdict:
+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 (infrastructure-level problem, not a real UI issue)
+   - `escalate` — preview server failed to start, OR axe threw ≥3 consecutive times, OR Playwright chromium missing.
 
-7. Teardown:
+9. Teardown:
    ```bash
    kill $SERVER_PID 2>/dev/null || true
    cd {{repo_root}}

package/skills/cloverleaf-qa.md

@@ -21,7 +21,12 @@ description: Run the QA agent on a task in the `qa` state (full pipeline only).
 
 4. Load QA rules JSON:
    ```bash
-   cat ~/.claude/plugins/cloverleaf/config/qa-rules.json
+   # Consumer override takes precedence over the package default.
+   if [ -f "<repo_root>/.cloverleaf/config/qa-rules.json" ]; then
+     cat "<repo_root>/.cloverleaf/config/qa-rules.json"
+   else
+     cat ~/.claude/plugins/cloverleaf/config/qa-rules.json
+   fi
    ```
    Capture for the subagent as `qa_rules`.
 

package/skills/cloverleaf-ui-review.md

@@ -1,6 +1,6 @@
 ---
 name: cloverleaf-ui-review
-description: Run the UI Reviewer agent on a task in the `ui-review` state (full pipeline only). Dispatches a subagent to run Playwright + axe-core against a local preview of the feature branch; emits feedback envelope; advances ui-review → qa on pass or loops back to implementing on bounce. Usage — /cloverleaf-ui-review <TASK-ID>.
+description: Run the UI Reviewer agent on a task in the `ui-review` state (full pipeline only). Computes diff-affected routes via CLI; if empty, skips axe and advances ui-review → qa. Otherwise dispatches a subagent with Playwright + axe-core scoped to those routes. Usage — /cloverleaf-ui-review <TASK-ID>.
 ---
 
 # Cloverleaf — ui-review
@@ -27,47 +27,67 @@ description: Run the UI Reviewer agent on a task in the `ui-review` state (full
 
 3. Confirm feature branch exists: `git rev-parse --verify cloverleaf/<TASK-ID>`. If missing, report and stop.
 
-4. Allocate a free `preview_port` via Node:
+4. Compute affected routes:
+   ```bash
+   AFFECTED=$(~/.claude/plugins/cloverleaf/bin/cloverleaf-cli affected-routes <repo_root> <TASK-ID>)
+   ```
+
+5. **Empty-set early-exit.** If `AFFECTED` is `[]`, skip the subagent entirely:
+   ```bash
+   cloverleaf-cli advance-status <repo_root> <TASK-ID> qa agent '' full_pipeline
+   cd <repo_root>
+   git add .cloverleaf/
+   git commit -m "cloverleaf: <TASK-ID> ui-review skipped (no renderable routes) → qa"
+   ```
+   Report: "✓ UI Review skipped (no renderable routes affected). State → qa. Next: `/cloverleaf-qa <TASK-ID>`."
+   Stop here.
+
+6. Allocate a free preview port:
    ```bash
    PREVIEW_PORT=$(node -e "const net=require('net');const s=net.createServer();s.listen(0,()=>{console.log(s.address().port);s.close()})")
    ```
 
-5. Compute diff for the subagent context:
+7. Compute diff:
    ```bash
    git diff main..cloverleaf/<TASK-ID>
    ```
 
-6. Dispatch the UI Reviewer subagent via the Task tool:
+8. **Browser cache env var.** Before the Task-tool dispatch, ensure `PLAYWRIGHT_BROWSERS_PATH=~/.cache/ms-playwright` is exported so the subagent inherits it. This keeps Playwright from re-downloading ~300 MB of browser binaries inside the worktree.
+
+9. Dispatch the UI Reviewer subagent via the Task tool:
    - `subagent_type`: `general-purpose`
    - `model`: `sonnet`
-   - Prompt: contents of `~/.claude/plugins/cloverleaf/prompts/ui-reviewer.md` with substitutions for `{{task}}`, `{{diff}}`, `{{branch}}`, `{{base_branch}}`, `{{repo_root}}`, `{{preview_port}}`.
+   - Prompt: contents of `~/.claude/plugins/cloverleaf/prompts/ui-reviewer.md` with substitutions:
+     - `{{task}}`, `{{diff}}`, `{{branch}}`, `{{base_branch}}`, `{{repo_root}}`, `{{preview_port}}`
+     - `{{affected_routes}}` → the value of `$AFFECTED` (verbatim — may be `"all"`, a JSON array, or `[]` but step 5 handled `[]` already)
 
-7. Parse the subagent's response. Expect `{"verdict": "pass"|"bounce"|"escalate", "summary": "...", "findings": [...]}`.
+10. Parse the subagent's response. Expect `{"verdict": "pass"|"bounce"|"escalate", "summary": "...", "findings": [...]}`.
 
-8. Branch on verdict:
+11. Branch on verdict:
 
-   **Pass:**
-   ```
-   cloverleaf-cli advance-status <repo_root> <TASK-ID> qa agent --path=full_pipeline
-   ```
-   Commit: `git add .cloverleaf/ && git commit -m "cloverleaf: <TASK-ID> ui-review passed → qa"`.
-   Report: "✓ UI Review passed. State → qa. Next: `/cloverleaf-qa <TASK-ID>`."
+    **Pass:**
+    ```
+    cloverleaf-cli advance-status <repo_root> <TASK-ID> qa agent '' full_pipeline
+    ```
+    Commit: `git add .cloverleaf/ && git commit -m "cloverleaf: <TASK-ID> ui-review passed → qa"`.
+    Report: "✓ UI Review passed. State → qa. Next: `/cloverleaf-qa <TASK-ID>`."
 
-   **Bounce:**
-   1. Write feedback envelope to temp file: `echo '<envelope-json>' > /tmp/cloverleaf-fb-u.json`
-   2. `cloverleaf-cli write-feedback <repo_root> <TASK-ID> /tmp/cloverleaf-fb-u.json --prefix=u` — captures path like `.cloverleaf/feedback/<TASK-ID>-u<N>.json`.
-   3. `cloverleaf-cli advance-status <repo_root> <TASK-ID> implementing agent --path=full_pipeline`
-   4. Commit: `git add .cloverleaf/ && git commit -m "cloverleaf: <TASK-ID> ui-review bounced → implementing"`.
-   5. Report: "✗ UI Review bounced. Findings: <summarize by severity>. State → implementing. Next: `/cloverleaf-implement <TASK-ID>`."
+    **Bounce:**
+    1. Write feedback: `echo '<envelope-json>' > /tmp/cloverleaf-fb-u.json`
+    2. `cloverleaf-cli write-feedback <repo_root> <TASK-ID> /tmp/cloverleaf-fb-u.json --prefix=u`
+    3. `cloverleaf-cli advance-status <repo_root> <TASK-ID> implementing agent '' full_pipeline`
+    4. Commit: `git add .cloverleaf/ && git commit -m "cloverleaf: <TASK-ID> ui-review bounced → implementing"`.
+    5. Report: "✗ UI Review bounced. Findings: <summary by severity>. State → implementing. Next: `/cloverleaf-implement <TASK-ID>`."
 
-   **Escalate:**
-   1. `cloverleaf-cli advance-status <repo_root> <TASK-ID> escalated agent`
-   2. Commit: `git add .cloverleaf/ && git commit -m "cloverleaf: <TASK-ID> ui-review escalated"`.
-   3. Report: "✗ UI Review escalated (infrastructure issue). Review and retry manually."
+    **Escalate:**
+    1. `cloverleaf-cli advance-status <repo_root> <TASK-ID> escalated agent`
+    2. Commit: `git add .cloverleaf/ && git commit -m "cloverleaf: <TASK-ID> ui-review escalated"`.
+    3. Report: "✗ UI Review escalated (infrastructure issue). Review and retry manually."
 
 ## Rules
 
 - Never push.
 - Do not modify source code — UI Reviewer is read-only.
 - Always teardown preview server + worktree on error.
+- Empty-set early-exit (step 5) skips the browser entirely — no Playwright invocation, no worktree.
 - On illegal state transition, report and stop without partial commits.