@cloverleaf/reference-impl 0.5.3 → 0.5.4

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "cloverleaf",
   "description": "Cloverleaf reference implementation — Claude Code skills for task scaffolding and the Delivery pipeline (implementer, documenter, reviewer, UI reviewer with multi-viewport visual diff, QA, merge).",
-  "version": "0.5.3",
+  "version": "0.5.4",
   "author": {
     "name": "Renato D'Arrigo",
     "email": "renato.darrigo@gmail.com"

package/README.md

@@ -41,6 +41,7 @@ v0.2 implements both paths of the Delivery track:
 - `/cloverleaf-document` — run Documenter *(new in v0.2)*
 - `/cloverleaf-review` — run Reviewer
 - `/cloverleaf-ui-review` — run UI Reviewer *(new in v0.2)*
+- `/cloverleaf-approve-baselines` — human baseline-approval gate; clears `baselines_pending` and advances `ui-review → qa` *(new in CLV-19)*
 - `/cloverleaf-qa` — run QA *(new in v0.2)*
 - `/cloverleaf-merge` — human gate (branches on state)
 - `/cloverleaf-run` — orchestrator (dispatches by `risk_class`)
@@ -145,7 +146,7 @@ The Reviewer never switches branches. It reads files via `git show` and runs tes
 
 ## Package layout
 
-- `lib/` — TypeScript library used by the CLI. State, events, feedback, IDs, paths. Includes `buildBaselinePath(repoRoot, browser, slug, viewport)` (`lib/visual-diff.ts`) for constructing canonical baseline paths under `.cloverleaf/baselines/{browser}/`. `lib/ui-browser.ts` exports `buildBrowserEscalationFinding` and `applyMaxCombinationsCap` (used by the UI Reviewer prompt for per-engine escalation and combination-count capping).
+- `lib/` — TypeScript library used by the CLI. State, events, feedback, IDs, paths. Includes `buildBaselinePath(repoRoot, browser, slug, viewport)` (`lib/visual-diff.ts`) for constructing canonical baseline paths under `.cloverleaf/baselines/{browser}/`. `lib/ui-browser.ts` exports `buildBrowserEscalationFinding` and `applyMaxCombinationsCap` (used by the UI Reviewer prompt for per-engine escalation and combination-count capping). `lib/ui-review-state.ts` exports `readUiReviewState`, `writeUiReviewState`, and `uiReviewStatePath` — the baseline-approval sidecar API for `.cloverleaf/runs/{taskId}/ui-review/state.json`.
 - `skills/` — Claude Code skill markdown files.
 - `prompts/` — Implementer/Reviewer subagent system prompts.
 - `examples/toy-repo/` — standalone demo repo.

package/VERSION

@@ -1 +1 @@
-0.5.3
+0.5.4

package/dist/cli.mjs

@@ -13,6 +13,8 @@
  *   latest-feedback <repoRoot> <taskId>
  *   emit-gate-decision <repoRoot> <workItemId> <gate> <decision> <actor> [--comment=<str>]
  *   ui-review-config --repo-root <repoRoot>
+ *   read-ui-review-state <repoRoot> <taskId>
+ *   write-ui-review-state <repoRoot> <taskId> <baselines_pending>
  *   plugin-root
  *   load-rfc <repoRoot> <id>
  *   save-rfc <repoRoot> <filePath>
@@ -46,6 +48,7 @@ import { loadSpike, saveSpike, advanceSpikeStatus } from './spike.mjs';
 import { loadPlan, savePlan, advancePlanStatus, materialiseTasksFromPlan } from './plan.mjs';
 import { loadDiscoveryConfig } from './discovery-config.mjs';
 import { prepWorktree } from './prep-worktree.mjs';
+import { readUiReviewState, writeUiReviewState } from './ui-review-state.mjs';
 function die(msg, code = 1) {
     process.stderr.write(msg + '\n');
     process.exit(code);
@@ -63,6 +66,8 @@ function usage(msg) {
         '  latest-feedback <repoRoot> <taskId>\n' +
         '  emit-gate-decision <repoRoot> <workItemId> <gate> <decision> <actor> [--comment=<str>]\n' +
         '  ui-review-config --repo-root <repoRoot>\n' +
+        '  read-ui-review-state <repoRoot> <taskId>\n' +
+        '  write-ui-review-state <repoRoot> <taskId> <baselines_pending>\n' +
         '  plugin-root\n' +
         '  load-rfc <repoRoot> <id>\n' +
         '  save-rfc <repoRoot> <filePath>\n' +
@@ -269,6 +274,22 @@ try {
             process.stdout.write(JSON.stringify(config, null, 2));
             process.exit(0);
         }
+        case 'read-ui-review-state': {
+            const [repoRoot, taskId] = rest;
+            if (!repoRoot || !taskId)
+                usage('read-ui-review-state requires <repoRoot> <taskId>');
+            const state = readUiReviewState(repoRoot, taskId);
+            process.stdout.write(JSON.stringify(state, null, 2) + '\n');
+            break;
+        }
+        case 'write-ui-review-state': {
+            const [repoRoot, taskId, pendingArg] = rest;
+            if (!repoRoot || !taskId || pendingArg === undefined)
+                usage('write-ui-review-state requires <repoRoot> <taskId> <baselines_pending>');
+            const baselines_pending = pendingArg === 'true' || pendingArg === '1';
+            writeUiReviewState(repoRoot, taskId, { baselines_pending });
+            break;
+        }
         case 'plugin-root': {
             process.stdout.write(getPluginRoot());
             process.exit(0);

package/dist/index.mjs

@@ -4,3 +4,4 @@ export * from './task.mjs';
 export * from './events.mjs';
 export * from './feedback.mjs';
 export * from './validate.mjs';
+export * from './ui-review-state.mjs';

package/dist/paths.mjs

@@ -24,3 +24,9 @@ export function spikesDir(repoRoot) {
 export function plansDir(repoRoot) {
     return resolve(cloverleafDir(repoRoot), 'plans');
 }
+export function runsDir(repoRoot) {
+    return resolve(cloverleafDir(repoRoot), 'runs');
+}
+export function uiReviewRunDir(repoRoot, taskId) {
+    return resolve(runsDir(repoRoot), taskId, 'ui-review');
+}

package/dist/ui-review-state.mjs

@@ -0,0 +1,40 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { uiReviewRunDir } from './paths.mjs';
+const STATE_FILENAME = 'state.json';
+/**
+ * Returns the canonical path for the ui-review sidecar state file:
+ *   .cloverleaf/runs/{taskId}/ui-review/state.json
+ */
+export function uiReviewStatePath(repoRoot, taskId) {
+    return join(uiReviewRunDir(repoRoot, taskId), STATE_FILENAME);
+}
+/**
+ * Reads the ui-review state sidecar from disk.
+ *
+ * Returns `{ baselines_pending: false }` when the file is absent — the
+ * absence of the file is treated as "no pending baselines", which lets the
+ * ui-review → qa transition proceed normally.
+ */
+export function readUiReviewState(repoRoot, taskId) {
+    const path = uiReviewStatePath(repoRoot, taskId);
+    if (!existsSync(path)) {
+        return { baselines_pending: false };
+    }
+    const raw = JSON.parse(readFileSync(path, 'utf-8'));
+    return { baselines_pending: Boolean(raw.baselines_pending) };
+}
+/**
+ * Writes the ui-review state sidecar to disk, creating intermediate directories
+ * as needed.
+ *
+ * @param repoRoot  Absolute path to the repository root.
+ * @param taskId    Task identifier (e.g. "CLV-42").
+ * @param state     The state to persist.
+ */
+export function writeUiReviewState(repoRoot, taskId, state) {
+    const dir = uiReviewRunDir(repoRoot, taskId);
+    mkdirSync(dir, { recursive: true });
+    const path = join(dir, STATE_FILENAME);
+    writeFileSync(path, JSON.stringify(state, null, 2) + '\n');
+}

package/lib/cli.ts

@@ -13,6 +13,8 @@
  *   latest-feedback <repoRoot> <taskId>
  *   emit-gate-decision <repoRoot> <workItemId> <gate> <decision> <actor> [--comment=<str>]
  *   ui-review-config --repo-root <repoRoot>
+ *   read-ui-review-state <repoRoot> <taskId>
+ *   write-ui-review-state <repoRoot> <taskId> <baselines_pending>
  *   plugin-root
  *   load-rfc <repoRoot> <id>
  *   save-rfc <repoRoot> <filePath>
@@ -48,6 +50,7 @@ import { loadSpike, saveSpike, advanceSpikeStatus, type SpikeDoc } from './spike
 import { loadPlan, savePlan, advancePlanStatus, materialiseTasksFromPlan, type PlanDoc } from './plan.js';
 import { loadDiscoveryConfig } from './discovery-config.js';
 import { prepWorktree } from './prep-worktree.js';
+import { readUiReviewState, writeUiReviewState } from './ui-review-state.js';
 
 function die(msg: string, code = 1): never {
   process.stderr.write(msg + '\n');
@@ -67,6 +70,8 @@ function usage(msg?: string): never {
       '  latest-feedback <repoRoot> <taskId>\n' +
       '  emit-gate-decision <repoRoot> <workItemId> <gate> <decision> <actor> [--comment=<str>]\n' +
       '  ui-review-config --repo-root <repoRoot>\n' +
+      '  read-ui-review-state <repoRoot> <taskId>\n' +
+      '  write-ui-review-state <repoRoot> <taskId> <baselines_pending>\n' +
       '  plugin-root\n' +
       '  load-rfc <repoRoot> <id>\n' +
       '  save-rfc <repoRoot> <filePath>\n' +
@@ -278,6 +283,23 @@ try {
       process.exit(0);
     }
 
+    case 'read-ui-review-state': {
+      const [repoRoot, taskId] = rest;
+      if (!repoRoot || !taskId) usage('read-ui-review-state requires <repoRoot> <taskId>');
+      const state = readUiReviewState(repoRoot, taskId);
+      process.stdout.write(JSON.stringify(state, null, 2) + '\n');
+      break;
+    }
+
+    case 'write-ui-review-state': {
+      const [repoRoot, taskId, pendingArg] = rest;
+      if (!repoRoot || !taskId || pendingArg === undefined)
+        usage('write-ui-review-state requires <repoRoot> <taskId> <baselines_pending>');
+      const baselines_pending = pendingArg === 'true' || pendingArg === '1';
+      writeUiReviewState(repoRoot, taskId, { baselines_pending });
+      break;
+    }
+
     case 'plugin-root': {
       process.stdout.write(getPluginRoot());
       process.exit(0);

package/lib/index.ts

@@ -4,3 +4,4 @@ export * from './task.js';
 export * from './events.js';
 export * from './feedback.js';
 export * from './validate.js';
+export * from './ui-review-state.js';

package/lib/paths.ts

@@ -33,3 +33,11 @@ export function spikesDir(repoRoot: string): string {
 export function plansDir(repoRoot: string): string {
   return resolve(cloverleafDir(repoRoot), 'plans');
 }
+
+export function runsDir(repoRoot: string): string {
+  return resolve(cloverleafDir(repoRoot), 'runs');
+}
+
+export function uiReviewRunDir(repoRoot: string, taskId: string): string {
+  return resolve(runsDir(repoRoot), taskId, 'ui-review');
+}

package/lib/ui-review-state.ts

@@ -0,0 +1,52 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { uiReviewRunDir } from './paths.js';
+
+export interface UiReviewState {
+  baselines_pending: boolean;
+}
+
+const STATE_FILENAME = 'state.json';
+
+/**
+ * Returns the canonical path for the ui-review sidecar state file:
+ *   .cloverleaf/runs/{taskId}/ui-review/state.json
+ */
+export function uiReviewStatePath(repoRoot: string, taskId: string): string {
+  return join(uiReviewRunDir(repoRoot, taskId), STATE_FILENAME);
+}
+
+/**
+ * Reads the ui-review state sidecar from disk.
+ *
+ * Returns `{ baselines_pending: false }` when the file is absent — the
+ * absence of the file is treated as "no pending baselines", which lets the
+ * ui-review → qa transition proceed normally.
+ */
+export function readUiReviewState(repoRoot: string, taskId: string): UiReviewState {
+  const path = uiReviewStatePath(repoRoot, taskId);
+  if (!existsSync(path)) {
+    return { baselines_pending: false };
+  }
+  const raw = JSON.parse(readFileSync(path, 'utf-8')) as UiReviewState;
+  return { baselines_pending: Boolean(raw.baselines_pending) };
+}
+
+/**
+ * Writes the ui-review state sidecar to disk, creating intermediate directories
+ * as needed.
+ *
+ * @param repoRoot  Absolute path to the repository root.
+ * @param taskId    Task identifier (e.g. "CLV-42").
+ * @param state     The state to persist.
+ */
+export function writeUiReviewState(
+  repoRoot: string,
+  taskId: string,
+  state: UiReviewState,
+): void {
+  const dir = uiReviewRunDir(repoRoot, taskId);
+  mkdirSync(dir, { recursive: true });
+  const path = join(dir, STATE_FILENAME);
+  writeFileSync(path, JSON.stringify(state, null, 2) + '\n');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloverleaf/reference-impl",
-  "version": "0.5.3",
+  "version": "0.5.4",
   "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

@@ -100,7 +100,7 @@ Do not attempt to launch a missing engine — fail fast with `verdict: "escalate
 7. **Verify browser binaries** — before starting any browser session:
    - Check each engine in `{{ui_review_config}}.browsers` against `PLAYWRIGHT_BROWSERS_PATH`.
    - Collect all missing engines.
-   - If any engine is missing, call `buildBrowserEscalationFinding(engine, process.platform)` for each, teardown the worktree (step 11), and return `verdict: "escalate"` with those findings.
+   - If any engine is missing, call `buildBrowserEscalationFinding(engine, process.platform)` for each, teardown the worktree (step 13), and return `verdict: "escalate"` with those findings.
 
 8. **Per-browser outer loop** — for each `browser` in `{{ui_review_config}}.browsers`:
 
@@ -156,7 +156,21 @@ Do not attempt to launch a missing engine — fail fast with `verdict: "escalate
     - `bounce` — ≥1 non-visual-diff, non-cap finding with severity `blocker` or `error`
     - `escalate` — preview server failed to start, OR axe threw ≥3 consecutive times, OR any required browser binary was absent.
 
-12. Teardown:
+12. **Write ui-review state sidecar** — after all browser passes complete and before teardown, determine whether any `compareVisual` call returned `new-baseline` or `dimension-mismatch` across all routes, viewports, and browsers in this run.
+
+    - If **yes**: write `{{repo_root}}/.cloverleaf/runs/{{taskId}}/ui-review/state.json` containing:
+      ```json
+      {"baselines_pending": true}
+      ```
+      (Create intermediate directories as needed.)
+    - If **no**: write `{{repo_root}}/.cloverleaf/runs/{{taskId}}/ui-review/state.json` containing:
+      ```json
+      {"baselines_pending": false}
+      ```
+
+    This sidecar is the baseline-approval gate read by the `cloverleaf-ui-review` skill. Writing `baselines_pending: false` explicitly (rather than omitting the file) lets the skill distinguish "no new baselines" from "reviewer did not run at all".
+
+13. Teardown:
     ```bash
     kill $SERVER_PID 2>/dev/null || true
     cd {{repo_root}}
@@ -166,7 +180,7 @@ Do not attempt to launch a missing engine — fail fast with `verdict: "escalate
 ## Tool constraints
 
 - Read-only for source files and tests.
-- You MAY write under `{{repo_root}}/.cloverleaf/baselines/` and `{{repo_root}}/.cloverleaf/runs/{taskId}/ui-review/` on the feature branch — these are the baselines and artifacts.
+- You MAY write under `{{repo_root}}/.cloverleaf/baselines/` and `{{repo_root}}/.cloverleaf/runs/{taskId}/ui-review/` on the feature branch — these are the baselines, artifacts, and the `state.json` sidecar.
 - Use `git worktree`: do NOT `git checkout` in the main working directory.
 - Always teardown the server and worktree, even on error.
 

package/skills/cloverleaf-approve-baselines/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: cloverleaf-approve-baselines
+description: Human baseline-approval gate for the Cloverleaf UI Review pipeline. When the UI Reviewer captures new or resized visual baselines it sets baselines_pending=true in .cloverleaf/runs/{taskId}/ui-review/state.json and blocks the ui-review → qa transition. Run this skill after inspecting the new baseline images to approve them and allow the task to advance to qa. Usage — /cloverleaf-approve-baselines <TASK-ID>.
+---
+
+# Cloverleaf — approve-baselines
+
+## Trigger condition
+
+This skill is invoked **only** when the `cloverleaf-ui-review` skill reports that `baselines_pending` is `true` — i.e., the UI Reviewer captured at least one `new-baseline` or `dimension-mismatch` result during its run, meaning one or more baseline PNGs under `.cloverleaf/baselines/{browser}/` were created or replaced.
+
+Do not run this skill if the task is not in `ui-review` status or if `state.json` already has `baselines_pending: false`.
+
+## Effect
+
+1. Writes `baselines_pending: false` to `.cloverleaf/runs/{taskId}/ui-review/state.json`.
+2. Advances the task from `ui-review` → `qa` via the normal agent transition.
+3. Commits the updated state and status to the feature branch.
+
+---
+
+## Steps
+
+0. Pre-flight:
+
+   ```bash
+   cd <repo_root>
+   current=$(git rev-parse --abbrev-ref HEAD)
+   if [ "$current" != "main" ]; then git checkout main; fi
+   ```
+
+   If main has uncommitted changes, stop and report.
+
+1. Capture the TASK-ID argument.
+
+2. Load the task and verify status:
+   ```bash
+   cloverleaf-cli load-task <repo_root> <TASK-ID>
+   ```
+   Verify `status === "ui-review"`. If not, report and stop.
+
+3. Read the current ui-review state:
+   ```bash
+   cloverleaf-cli read-ui-review-state <repo_root> <TASK-ID>
+   ```
+   If `baselines_pending` is already `false` (or the file is absent), report that no approval is needed and stop.
+
+4. Present the new baseline images to the human for review. The baselines live at:
+   ```
+   <repo_root>/.cloverleaf/baselines/{browser}/{slug}-{viewport}.png
+   ```
+   List the files that were modified since the last commit on the feature branch:
+   ```bash
+   git diff --name-only main..cloverleaf/<TASK-ID> -- .cloverleaf/baselines/
+   ```
+   Display the list. Ask the human to confirm they have reviewed the images and approve the baselines before proceeding.
+
+5. Once approved, write `baselines_pending: false`:
+   ```bash
+   cloverleaf-cli write-ui-review-state <repo_root> <TASK-ID> false
+   ```
+
+6. Advance the task to qa:
+   ```bash
+   cloverleaf-cli advance-status <repo_root> <TASK-ID> qa agent '' full_pipeline
+   ```
+
+7. Commit the changes to the feature branch:
+   ```bash
+   cd <repo_root>
+   git add .cloverleaf/
+   git commit -m "cloverleaf: <TASK-ID> baselines approved → qa"
+   ```
+
+8. Report:
+   > "✓ Baselines approved. `baselines_pending` cleared. State → qa. Next: `/cloverleaf-qa <TASK-ID>`."
+
+---
+
+## Rules
+
+- Never push.
+- Do not modify source code or test files.
+- Do not skip step 4 — the human must acknowledge the baseline images before approval is recorded.
+- On illegal state transition, report and stop without partial commits.

package/skills/cloverleaf-ui-review/SKILL.md

@@ -74,14 +74,36 @@ description: Run the UI Reviewer agent on a task in the `ui-review` state (full
 
 11. Parse the subagent's response. Expect `{"verdict": "pass"|"bounce"|"escalate", "summary": "...", "findings": [...]}`.
 
-12. Branch on verdict:
-
-    **Pass:**
+12. **Read the baseline-approval sidecar** (after the subagent completes, regardless of verdict):
+    ```bash
+    UI_STATE=$(cloverleaf-cli read-ui-review-state <repo_root> <TASK-ID>)
+    BASELINES_PENDING=$(echo "$UI_STATE" | node -e "process.stdout.write(JSON.parse(require('fs').readFileSync('/dev/stdin','utf-8')).baselines_pending ? 'true' : 'false')")
     ```
-    cloverleaf-cli advance-status <repo_root> <TASK-ID> qa agent '' full_pipeline
+    Or more concisely:
+    ```bash
+    BASELINES_PENDING=$(cloverleaf-cli read-ui-review-state <repo_root> <TASK-ID> | node -e "const s=require('fs').readFileSync('/dev/stdin','utf-8'); process.stdout.write(JSON.parse(s).baselines_pending?'true':'false')")
     ```
-    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>`."
+
+13. Branch on verdict:
+
+    **Pass:**
+
+    Check `BASELINES_PENDING`:
+
+    - If `BASELINES_PENDING` is `true`:
+      - Do NOT advance to `qa`.
+      - Commit artifacts: `git add .cloverleaf/ && git commit -m "cloverleaf: <TASK-ID> ui-review passed (baselines pending approval)"`.
+      - Report:
+        > "✓ UI Review passed (no a11y errors), but **baselines_pending** is true: one or more new or resized visual baselines were captured and require human approval before advancing to qa.
+        > Run `/cloverleaf-approve-baselines <TASK-ID>` to review the new baseline images and approve them, which will clear the flag and advance the task to qa."
+      - Stop here (task remains in `ui-review` status).
+
+    - If `BASELINES_PENDING` is `false` (or state.json is absent):
+      ```
+      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: `echo '<envelope-json>' > /tmp/cloverleaf-fb-u.json`