@cloverleaf/reference-impl 0.1.1 → 0.2.0

package/dist/ui-paths.mjs

@@ -0,0 +1,25 @@
+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', 'ui-paths.json');
+export function loadDefaultPatterns() {
+    if (!existsSync(DEFAULT_CONFIG))
+        return ['site/**'];
+    const doc = JSON.parse(readFileSync(DEFAULT_CONFIG, 'utf-8'));
+    return Array.isArray(doc.patterns) ? doc.patterns : ['site/**'];
+}
+function globToRegex(pattern) {
+    const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+    const regex = escaped
+        .replace(/\*\*/g, '\u0000')
+        .replace(/\*/g, '[^/]*')
+        .replace(/\u0000/g, '.*');
+    return new RegExp(`^${regex}$`);
+}
+export function matchesUiPaths(changedFiles, patterns) {
+    if (changedFiles.length === 0)
+        return false;
+    const regexes = patterns.map(globToRegex);
+    return changedFiles.some((f) => regexes.some((r) => r.test(f)));
+}

package/dist/validate.mjs

@@ -0,0 +1,40 @@
+import Ajv from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+import { readFileSync, readdirSync } from 'node:fs';
+import { createRequire } from 'node:module';
+const req = createRequire(import.meta.url);
+const pkgDir = req.resolve('@cloverleaf/standard/package.json').replace(/\/package\.json$/, '');
+let ajvInstance = null;
+const compiledCache = new Map();
+function getAjv() {
+    if (ajvInstance)
+        return ajvInstance;
+    const ajv = new Ajv({ strict: false, validateFormats: true, allErrors: true });
+    addFormats(ajv);
+    const schemaFiles = readdirSync(`${pkgDir}/schemas`).filter(f => f.endsWith('.schema.json'));
+    for (const file of schemaFiles) {
+        const schema = JSON.parse(readFileSync(`${pkgDir}/schemas/${file}`, 'utf-8'));
+        ajv.addSchema(schema);
+    }
+    ajvInstance = ajv;
+    return ajv;
+}
+function getValidator(schemaId) {
+    const cached = compiledCache.get(schemaId);
+    if (cached)
+        return cached;
+    const ajv = getAjv();
+    const validator = ajv.getSchema(schemaId);
+    if (!validator)
+        throw new Error(`Schema not registered: ${schemaId}`);
+    compiledCache.set(schemaId, validator);
+    return validator;
+}
+export function validateOrThrow(schemaId, doc) {
+    const validate = getValidator(schemaId);
+    if (!validate(doc)) {
+        const violations = (validate.errors ?? []).length;
+        const detail = JSON.stringify(validate.errors, null, 2);
+        throw new Error(`Schema validation failed: ${violations} violation(s) against ${schemaId}\n${detail}`);
+    }
+}

package/install.sh

@@ -28,6 +28,9 @@ fi
 
 mkdir -p "${INSTALL_ROOT}/skills" "${INSTALL_ROOT}/prompts" "${INSTALL_ROOT}/bin"
 
+# Symlink config directory
+ln -sf "${SCRIPT_DIR}/config" "${INSTALL_ROOT}/config"
+
 # Symlink skills
 for f in "${SCRIPT_DIR}/skills/"*.md; do
   name="$(basename "$f")"

package/lib/cli.ts

@@ -15,11 +15,13 @@
  */
 
 import { readFileSync } from 'node:fs';
+import { execSync } from 'node:child_process';
 import { loadTask } from './state.js';
 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 type { FeedbackEnvelope } from './feedback.js';
 
 function die(msg: string, code = 1): never {
@@ -98,14 +100,18 @@ try {
     }
 
     case 'write-feedback': {
-      const [repoRoot, taskId, envelopeJsonPath] = rest;
+      const positional = rest.filter((a: string) => !a.startsWith('--'));
+      const flags = rest.filter((a: string) => a.startsWith('--'));
+      const [repoRoot, taskId, envelopeJsonPath] = positional;
       if (!repoRoot || !taskId || !envelopeJsonPath)
         usage('write-feedback requires <repoRoot> <taskId> <envelopeJsonPath>');
+      const prefixFlag = flags.find((f: string) => f.startsWith('--prefix='));
+      const prefix = prefixFlag ? prefixFlag.split('=')[1] : 'r';
       const envelope = JSON.parse(readFileSync(envelopeJsonPath, 'utf-8')) as FeedbackEnvelope;
       const match = taskId.match(/^(.+)-\d+$/);
       if (!match) die(`Invalid taskId format: ${taskId}`);
       const project = match[1];
-      const writtenPath = writeFeedback(repoRoot, { project, taskId, envelope });
+      const writtenPath = writeFeedback(repoRoot, { project, taskId, envelope, prefix });
       process.stdout.write(writtenPath + '\n');
       break;
     }
@@ -158,6 +164,33 @@ try {
       break;
     }
 
+    case 'detect-ui-paths': {
+      const [repoRoot, taskId] = rest;
+      if (!repoRoot || !taskId) {
+        console.error('usage: detect-ui-paths <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 patterns = loadDefaultPatterns();
+      const result = matchesUiPaths(changed, patterns);
+      process.stdout.write(`${result}\n`);
+      process.exit(0);
+    }
+
     default:
       usage(`Unknown command: ${command}`);
   }

package/lib/feedback.ts

@@ -32,6 +32,9 @@ export interface WriteFeedbackParams {
   project: string;
   taskId: string; // e.g. "ACME-001"
   envelope: FeedbackEnvelope;
+  /** Prefix letter for the feedback file counter. Defaults to 'r' (Reviewer).
+   *  Use 'u' for UI Reviewer, 'q' for QA. */
+  prefix?: string;
 }
 
 export function writeFeedback(repoRoot: string, params: WriteFeedbackParams): string {
@@ -42,8 +45,9 @@ export function writeFeedback(repoRoot: string, params: WriteFeedbackParams): st
   if (project !== params.project) {
     throw new Error(`project mismatch: taskId=${params.taskId} vs project=${params.project}`);
   }
-  const iteration = nextFeedbackIteration(repoRoot, project, taskNum);
-  const filename = `${params.taskId}-r${iteration}.json`;
+  const prefix = params.prefix ?? 'r';
+  const iteration = nextFeedbackIteration(repoRoot, project, taskNum, prefix);
+  const filename = `${params.taskId}-${prefix}${iteration}.json`;
   const path = join(feedbackDir(repoRoot), filename);
   mkdirSync(feedbackDir(repoRoot), { recursive: true });
   validateOrThrow('https://cloverleaf.example/schemas/feedback.schema.json', params.envelope);

package/lib/ids.ts

@@ -24,11 +24,12 @@ export function nextEventId(repoRoot: string, project: string): number {
   return nums.length === 0 ? 1 : Math.max(...nums) + 1;
 }
 
-export function nextFeedbackIteration(repoRoot: string, project: string, taskNum: number): number {
+export function nextFeedbackIteration(repoRoot: string, project: string, taskNum: number, prefix = 'r'): number {
   const dir = feedbackDir(repoRoot);
   if (!existsSync(dir)) return 1;
   const suffix = String(taskNum).padStart(3, '0');
-  const re = new RegExp(`^${escapeRegex(project)}-${suffix}-r(\\d+)\\.json$`);
+  const escapedPrefix = escapeRegex(prefix);
+  const re = new RegExp(`^${escapeRegex(project)}-${suffix}-${escapedPrefix}(\\d+)\\.json$`);
   const nums = readdirSync(dir)
     .map((f) => f.match(re))
     .filter((m): m is RegExpMatchArray => !!m)

package/lib/ports.ts

@@ -0,0 +1,19 @@
+import { createServer } from 'node:net';
+
+export function getFreePort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const server = createServer();
+    server.unref();
+    server.once('error', reject);
+    server.listen(0, () => {
+      const addr = server.address();
+      if (addr && typeof addr === 'object') {
+        const port = addr.port;
+        server.close(() => resolve(port));
+      } else {
+        server.close();
+        reject(new Error('could not determine port'));
+      }
+    });
+  });
+}

package/lib/qa-rules.ts

@@ -0,0 +1,23 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { matchesUiPaths } from './ui-paths.js';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const DEFAULT_CONFIG = join(here, '..', 'config', 'qa-rules.json');
+
+export interface QaRule {
+  cwd: string;
+  match: string[];
+  command: string;
+}
+
+export 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 : [];
+}
+
+export function selectTestCommands(changedFiles: string[], rules: QaRule[]): QaRule[] {
+  return rules.filter((rule) => matchesUiPaths(changedFiles, rule.match));
+}

package/lib/state.ts

@@ -32,7 +32,7 @@ export interface TaskDoc {
 
 export interface ProjectDoc {
   key: string;
-  name?: string;
+  name: string;
   [key: string]: unknown;
 }
 

package/lib/ui-paths.ts

@@ -0,0 +1,27 @@
+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', 'ui-paths.json');
+
+export 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/**'];
+}
+
+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}$`);
+}
+
+export function matchesUiPaths(changedFiles: string[], patterns: string[]): boolean {
+  if (changedFiles.length === 0) return false;
+  const regexes = patterns.map(globToRegex);
+  return changedFiles.some((f) => regexes.some((r) => r.test(f)));
+}

package/lib/validate.ts

@@ -1,29 +1,11 @@
 import Ajv, { type ValidateFunction } from 'ajv/dist/2020.js';
 import addFormats from 'ajv-formats';
-import { readFileSync } from 'node:fs';
+import { readFileSync, readdirSync } from 'node:fs';
 import { createRequire } from 'node:module';
 
 const req = createRequire(import.meta.url);
 const pkgDir = req.resolve('@cloverleaf/standard/package.json').replace(/\/package\.json$/, '');
 
-const SCHEMA_FILES = [
-  'work-item.schema.json',
-  'project.schema.json',
-  'task.schema.json',
-  'rfc.schema.json',
-  'spike.schema.json',
-  'plan.schema.json',
-  'feedback.schema.json',
-  'problem.schema.json',
-  'status-transition-event.schema.json',
-  'gate-decision-event.schema.json',
-  'status-transitions.schema.json',
-  'dependency-dag.schema.json',
-  'extensions.schema.json',
-  'path-rules.schema.json',
-  'risk-classifier-rules.schema.json',
-];
-
 let ajvInstance: Ajv | null = null;
 const compiledCache = new Map<string, ValidateFunction>();
 
@@ -31,7 +13,8 @@ function getAjv(): Ajv {
   if (ajvInstance) return ajvInstance;
   const ajv = new Ajv({ strict: false, validateFormats: true, allErrors: true });
   addFormats(ajv);
-  for (const file of SCHEMA_FILES) {
+  const schemaFiles = readdirSync(`${pkgDir}/schemas`).filter(f => f.endsWith('.schema.json'));
+  for (const file of schemaFiles) {
     const schema = JSON.parse(readFileSync(`${pkgDir}/schemas/${file}`, 'utf-8'));
     ajv.addSchema(schema);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloverleaf/reference-impl",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Reference implementation of the Cloverleaf methodology as Claude Code skills. Implements the Tight Loop (Implementer + Reviewer).",
   "type": "module",
   "license": "MIT",
@@ -26,25 +26,31 @@
     "skills",
     "lib",
     "prompts",
+    "config",
     "install.sh",
     "README.md",
-    "VERSION"
+    "VERSION",
+    "dist"
   ],
   "publishConfig": {
     "access": "public"
   },
   "bin": {
-    "cloverleaf-cli": "./lib/cli.ts"
+    "cloverleaf-cli": "./dist/cli.mjs"
   },
   "scripts": {
-    "test": "vitest run",
+    "test": "tsc --noEmit && vitest run",
     "test:watch": "vitest",
-    "prepublishOnly": "npm test"
+    "typecheck": "tsc --noEmit",
+    "build": "tsc -p tsconfig.build.json && node scripts/rename-to-mjs.mjs",
+    "prepublishOnly": "npm test && npm run build"
   },
   "dependencies": {
     "@cloverleaf/standard": "^0.3.0",
     "ajv": "^8.17.1",
-    "ajv-formats": "^3.0.1"
+    "ajv-formats": "^3.0.1",
+    "playwright": "^1.47.0",
+    "axe-core": "^4.10.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/prompts/documenter.md

@@ -0,0 +1,72 @@
+# Documenter Agent
+
+You are the Cloverleaf Documenter. Your job: produce doc-only commits that update AI-facing docs to reflect the code changes in a task's feature branch. You do NOT touch source code. You do NOT write new prose or new top-level sections. You only edit existing doc structures and append entries to CHANGELOGs.
+
+## Input
+
+- **Task**: {{task}}
+- **Branch**: {{branch}} (already exists; contains Implementer's commits)
+- **Base branch**: {{base_branch}}
+- **Repo root**: {{repo_root}}
+- **Diff from base**: {{diff}}
+
+## Tool constraints
+
+- Use `git worktree add <temp> {{branch}}` to work on an isolated checkout. Do NOT `git checkout` in the main working directory.
+- Only edit files under:
+  - `<package>/CHANGELOG.md` (create `## [Unreleased]` section if missing)
+  - `<package>/README.md`
+  - `<package>/docs/*.md`
+  - Root `CHANGELOG.md`, root `README.md`
+- Never touch source code (`*.ts`, `*.tsx`, `*.js`, `*.py`, `*.astro` bodies, etc.)
+- Never create new top-level sections. If a change warrants one, return `commits_added: 0` with a summary noting the deferral.
+- Never set release dates or version numbers in CHANGELOGs. Always write under `## [Unreleased]`.
+
+## File-path rules
+
+Inspect the diff. For each category below that matches, update the listed docs:
+
+| Diff touches | Docs to update |
+|---|---|
+| `standard/src/**`, `standard/schemas/**`, `standard/conformance/**` | `standard/CHANGELOG.md` (Unreleased), relevant `standard/docs/*.md` sections if behavior/conformance changed |
+| `reference-impl/lib/**`, `reference-impl/skills/**`, `reference-impl/prompts/**` | `reference-impl/CHANGELOG.md` (Unreleased), `reference-impl/README.md` if public surface changed (new skill, CLI command, exported lib symbol) |
+| `site/src/**`, `site/public/**` | `site/CHANGELOG.md` ONLY if that file already exists; otherwise skip |
+| Root-level package additions, version bumps | Root `README.md`, root `CHANGELOG.md` |
+| Only tests, configs, or `.cloverleaf/**` touched | No doc commits — return `commits_added: 0` with summary |
+
+## CHANGELOG format
+
+Append a single bullet to an `## [Unreleased]` section under the appropriate `### Added / ### Changed / ### Fixed` subheading. Infer the subheading from commit messages + diff shape:
+
+- `feat:` or new files → `### Added`
+- `fix:` → `### Fixed`
+- `refactor:`, `chore:`, other → `### Changed`
+
+If `## [Unreleased]` does not exist, create it at the top of the CHANGELOG (right after the title line or any badges).
+
+## README/docs surgery
+
+- Only edit existing sections. If a change warrants a new section, defer.
+- Keep edits surgical: update a version number in a code block, add a new entry to an existing list, revise a single paragraph to reflect changed behavior.
+- If unsure, prefer a shorter, more conservative edit over rewriting prose.
+
+## Commit discipline
+
+- One commit per file touched.
+- Commit message: `docs(<scope>): <short>` where `<scope>` is the package name (`standard`, `reference-impl`, `site`, or `repo` for root-level).
+- All commits land on `{{branch}}` (the feature branch).
+- After all commits land, run `git worktree remove --force <temp>` to clean up.
+
+## Output
+
+Respond with exactly one JSON object and nothing else:
+
+```json
+{
+  "commits_added": <integer ≥ 0>,
+  "files_changed": ["<relative/path1>", "<relative/path2>"],
+  "summary": "<one-sentence summary of changes>"
+}
+```
+
+If you cannot determine safe edits and no doc update is warranted, return `{"commits_added": 0, "files_changed": [], "summary": "No AI-facing docs required updating."}`.

package/prompts/qa.md

@@ -0,0 +1,82 @@
+# QA Agent
+
+You are the Cloverleaf QA agent. Your job: run the appropriate test suites for a task's changes against an isolated checkout of the feature branch. You do NOT use a browser (UI Reviewer owns accessibility). You are read-only — no source edits.
+
+## Input
+
+- **Task**: {{task}}
+- **Branch**: {{branch}}
+- **Base branch**: {{base_branch}}
+- **Repo root**: {{repo_root}}
+- **Diff from base**: {{diff}}
+- **QA rules (JSON)**: {{qa_rules}} — array of `{cwd, match, command}` entries. Each rule's `match` is a list of glob patterns; if any changed file matches, run the `command` in the `cwd` subdirectory.
+
+## Contract note
+
+The Standard's QA contract requires a `preview_uri`. You were passed the sentinel `about:blank` because QA in this implementation is test-runner only (no preview). Ignore `preview_uri` in your logic.
+
+## Runtime procedure
+
+1. Set up isolated worktree:
+   ```bash
+   TMPDIR=$(mktemp -d)
+   git worktree add "$TMPDIR" {{branch}}
+   ```
+
+2. Inspect the changed files (from the diff). For each QA rule whose `match` patterns match ≥1 changed file, queue its command.
+
+3. If no rules match (e.g., the diff only changes `.cloverleaf/**` or tests unrelated to any package), skip with a `pass` verdict — nothing testable in this diff:
+   ```json
+   {"verdict": "pass", "summary": "No testable packages changed.", "findings": [], "results": {"passed": 0, "failed": 0, "total": 0}}
+   ```
+
+4. For each queued command:
+   - Run it in `"$TMPDIR/<cwd>"`
+   - Capture stdout, stderr, exit code
+   - Parse test output to extract `passed`, `failed`, `total`:
+     - Vitest: `Tests  N passed | M failed (T)` or similar
+     - npm build: treat exit 0 as `{passed: 1, failed: 0, total: 1}`, non-zero as `{passed: 0, failed: 1, total: 1}`
+   - On failure, collect up to 10 failure names/messages as findings with `severity: "error"` and `rule: "qa.<suite>.<test-name>"`
+
+5. Aggregate results: sum `passed`, `failed`, `total` across all runs.
+
+6. Compute verdict:
+   - `pass` — every command exited 0 AND aggregated `failed === 0`
+   - `bounce` — any command exited non-zero OR `failed > 0`; findings list the first ~10 failures
+   - `escalate` — any command failed deterministically on 3 consecutive retries (attempt the rerun yourself), OR `npm ci` itself failed (infrastructure problem)
+
+7. Teardown:
+   ```bash
+   cd {{repo_root}}
+   git worktree remove --force "$TMPDIR"
+   ```
+
+## Tool constraints
+
+- Read-only. Do NOT edit source files.
+- Use `git worktree`: do NOT `git checkout` in the main working directory.
+- Always teardown the worktree, even on error.
+
+## Output
+
+Respond with exactly one JSON object and nothing else:
+
+```json
+{
+  "verdict": "pass" | "bounce" | "escalate",
+  "summary": "<one-sentence summary>",
+  "findings": [
+    {
+      "severity": "error",
+      "rule": "qa.<suite>.<test-name>",
+      "message": "<test failure message>",
+      "location": "<file:line if known>"
+    }
+  ],
+  "results": {
+    "passed": <integer>,
+    "failed": <integer>,
+    "total": <integer>
+  }
+}
+```

package/prompts/ui-reviewer.md

@@ -0,0 +1,93 @@
+# 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.
+
+## Input
+
+- **Task**: {{task}}
+- **Branch**: {{branch}}
+- **Base branch**: {{base_branch}}
+- **Repo root**: {{repo_root}}
+- **Diff from base**: {{diff}}
+- **Preview port**: {{preview_port}} (an already-allocated free local port; use it for the dev server)
+
+## Scope (v0.2)
+
+- 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.
+
+## Runtime procedure
+
+1. 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:
+   ```bash
+   cd "$TMPDIR/site"
+   npm ci
+   npm run dev -- --port={{preview_port}} &
+   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. 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`:
+     ```javascript
+     import axe from 'axe-core';
+     const results = await axe.run(document);
+     ```
+   - Collect all violations
+
+5. 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:
+   - `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)
+
+7. 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.
+- 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.
+
+```json
+{
+  "verdict": "pass" | "bounce" | "escalate",
+  "summary": "<one-sentence summary>",
+  "findings": [
+    {
+      "severity": "blocker" | "error" | "warning" | "info",
+      "rule": "a11y.<rule-id>",
+      "message": "<rule description — include the page URL (e.g., 'at /guide/') in the message>"
+    }
+  ]
+}
+```
+
+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).