@cloverleaf/reference-impl 0.1.1 → 0.3.0

package/dist/qa-rules.mjs

@@ -0,0 +1,15 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { matchesUiPaths } from './ui-paths.mjs';
+const here = dirname(fileURLToPath(import.meta.url));
+const DEFAULT_CONFIG = join(here, '..', 'config', 'qa-rules.json');
+export function loadDefaultRules() {
+    if (!existsSync(DEFAULT_CONFIG))
+        return [];
+    const doc = JSON.parse(readFileSync(DEFAULT_CONFIG, 'utf-8'));
+    return Array.isArray(doc.rules) ? doc.rules : [];
+}
+export function selectTestCommands(changedFiles, rules) {
+    return rules.filter((rule) => matchesUiPaths(changedFiles, rule.match));
+}

package/dist/state.mjs

@@ -0,0 +1,97 @@
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { createRequire } from 'node:module';
+import { randomUUID } from 'node:crypto';
+import { tasksDir, projectsDir } from './paths.mjs';
+import { emitStatusTransition, formatReason } from './events.mjs';
+// Import validator from @cloverleaf/standard.
+// The standard package ships TypeScript source only with no exports map.
+// Vitest (via vite-node) resolves .js → .ts for workspace symlinked packages,
+// so the .js convention works here. If it ever fails with "module not found",
+// switch the specifier to '@cloverleaf/standard/validators/index.ts'.
+import { validateStatusTransitionLegality } from '@cloverleaf/standard/validators/index.js';
+import { validateOrThrow } from './validate.mjs';
+const req = createRequire(import.meta.url);
+export function loadTask(repoRoot, taskId) {
+    const path = join(tasksDir(repoRoot), `${taskId}.json`);
+    if (!existsSync(path))
+        throw new Error(`Task ${taskId} not found at ${path}`);
+    return JSON.parse(readFileSync(path, 'utf-8'));
+}
+export function saveTask(repoRoot, task) {
+    validateOrThrow('https://cloverleaf.example/schemas/task.schema.json', task);
+    const path = join(tasksDir(repoRoot), `${task.id}.json`);
+    writeFileSync(path, JSON.stringify(task, null, 2) + '\n');
+}
+export function loadProject(repoRoot, projectId) {
+    const path = join(projectsDir(repoRoot), `${projectId}.json`);
+    if (!existsSync(path))
+        throw new Error(`Project ${projectId} not found at ${path}`);
+    return JSON.parse(readFileSync(path, 'utf-8'));
+}
+function loadTaskStateMachine() {
+    // state-machines/task.json is a static JSON asset. Navigate from standard's
+    // package.json — no exports map support needed.
+    const pkgPath = req.resolve('@cloverleaf/standard/package.json');
+    const pkgDir = pkgPath.replace(/\/package\.json$/, '');
+    return JSON.parse(readFileSync(`${pkgDir}/state-machines/task.json`, 'utf-8'));
+}
+export function advanceStatus(repoRoot, taskId, toStatus, actor, options = {}) {
+    const task = loadTask(repoRoot, taskId);
+    const from = task.status;
+    const sm = loadTaskStateMachine();
+    // Read risk_class directly from the task (defaulting to 'low' if absent).
+    // The validator derives itemPath from workItem.risk_class: low → fast_lane, else full_pipeline.
+    // If caller passed options.path, translate it back to risk_class for the validator.
+    const riskClass = options.path === 'fast_lane' ? 'low'
+        : options.path === 'full_pipeline' ? 'high'
+            : (task.risk_class ?? 'low');
+    // Build a minimal Task-shaped object so the validator can resolve path-tagged transitions.
+    const workItemForValidator = {
+        type: 'task',
+        id: task.id,
+        project: task.project,
+        status: task.status,
+        risk_class: riskClass,
+        context: { rfc: { project: task.project, id: task.id } },
+        definition_of_done: task.definition_of_done,
+        acceptance_criteria: task.acceptance_criteria,
+    };
+    const reason = formatReason({ gate: options.gate, path: options.path });
+    const event = {
+        event_id: randomUUID(),
+        event_type: 'status_transition',
+        occurred_at: new Date().toISOString(),
+        work_item_id: { project: task.project, id: task.id },
+        work_item_type: 'task',
+        from_status: from,
+        to_status: toStatus,
+        actor: { kind: actor, id: actor },
+        ...(reason ? { reason } : {}),
+    };
+    const result = validateStatusTransitionLegality(event, sm, workItemForValidator);
+    if (!result.ok) {
+        const msgs = result.violations.map((v) => v.message).join('; ');
+        throw new Error(`Illegal transition ${from} → ${toStatus}: ${msgs}`);
+    }
+    // NEW: emit first, save second. validateStatusTransitionLegality stays above.
+    const emittedPath = emitStatusTransition(repoRoot, {
+        project: task.project,
+        workItemType: 'task',
+        workItemId: task.id,
+        from,
+        to: toStatus,
+        actor,
+        gate: options.gate,
+        path: options.path,
+    });
+    const proposed = { ...task, status: toStatus };
+    try {
+        saveTask(repoRoot, proposed);
+    }
+    catch (err) {
+        const inner = err instanceof Error ? err.message : String(err);
+        throw new Error(`orphan event written to ${emittedPath} but task save failed: ${inner}`);
+    }
+    return proposed;
+}

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")"
@@ -52,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

@@ -15,11 +15,14 @@
  */
 
 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 { computeAffectedRoutes, loadDefaultConfig } from './affected-routes.js';
 import type { FeedbackEnvelope } from './feedback.js';
 
 function die(msg: string, code = 1): never {
@@ -98,14 +101,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 +165,60 @@ 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);
+    }
+
+    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/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.3.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."}`.