@cloverleaf/reference-impl 0.2.0 → 0.3.0

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 |
@@ -54,10 +54,18 @@ Two JSON config files in `config/` (overridable per consumer project):
 
 ### 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`).
+- Astro `base` path is parsed best-effort; if misdetected, UI Reviewer may return escalate.
+
+### 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
 

package/VERSION

@@ -1 +1 @@
-0.2.0
+0.3.0

package/config/affected-routes.json

@@ -0,0 +1,12 @@
+{
+  "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/**"]
+}

package/dist/affected-routes.mjs

@@ -0,0 +1,66 @@
+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 : [],
+    };
+}
+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;
+        }
+        if (matchesAny(file, config.routeScope)) {
+            inScopeButUnmatched = true;
+        }
+    }
+    if (inScopeButUnmatched) {
+        return 'all';
+    }
+    return Array.from(routes).sort();
+}

package/dist/cli.mjs

@@ -21,6 +21,7 @@ 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 { computeAffectedRoutes, loadDefaultConfig } from './affected-routes.mjs';
 function die(msg, code = 1) {
     process.stderr.write(msg + '\n');
     process.exit(code);
@@ -181,6 +182,33 @@ try {
             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 = loadDefaultConfig();
+            const result = computeAffectedRoutes(changed, config);
+            process.stdout.write(`${JSON.stringify(result)}\n`);
+            process.exit(0);
+        }
         default:
             usage(`Unknown command: ${command}`);
     }

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,80 @@
+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[];
+}
+
+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 : [],
+  };
+}
+
+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;
+    }
+    if (matchesAny(file, config.routeScope)) {
+      inScopeButUnmatched = true;
+    }
+  }
+
+  if (inScopeButUnmatched) {
+    return 'all';
+  }
+  return Array.from(routes).sort();
+}

package/lib/cli.ts

@@ -22,6 +22,7 @@ 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 { computeAffectedRoutes, loadDefaultConfig } from './affected-routes.js';
 import type { FeedbackEnvelope } from './feedback.js';
 
 function die(msg: string, code = 1): never {
@@ -191,6 +192,33 @@ try {
       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 = loadDefaultConfig();
+      const result = computeAffectedRoutes(changed, config);
+      process.stdout.write(`${JSON.stringify(result)}\n`);
+      process.exit(0);
+    }
+
     default:
       usage(`Unknown command: ${command}`);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloverleaf/reference-impl",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "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,32 @@ 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: read `astro.config.*` in the worktree for a `base: '<path>'` entry. Default to empty string if not found or unparseable.
 
-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-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.