@cloverleaf/reference-impl 0.1.1 → 0.2.0

package/skills/cloverleaf-document.md

@@ -0,0 +1,73 @@
+---
+name: cloverleaf-document
+description: Run the Documenter agent on a task in the `implementing` state (full pipeline only). Dispatches a subagent to add doc-only commits to the feature branch, then advances implementing → documenting → review. Usage — /cloverleaf-document <TASK-ID>.
+---
+
+# Cloverleaf — document
+
+## Steps
+
+0. Ensure you are on `main`. State is authoritative on main. Run:
+
+   ```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 — the user must clean up first.
+
+1. Capture the TASK-ID argument.
+
+2. Load the task:
+   ```
+   ~/.claude/plugins/cloverleaf/bin/cloverleaf-cli load-task <repo_root> <TASK-ID>
+   ```
+   Verify `status === "implementing"`. Verify `risk_class === "high"`. If either check fails, report and stop.
+
+3. Confirm feature branch exists: `git rev-parse --verify cloverleaf/<TASK-ID>`. If missing, report the discrepancy and stop.
+
+4. Compute the diff (without checking out):
+   ```bash
+   git diff main..cloverleaf/<TASK-ID>
+   ```
+   Capture the output for the subagent.
+
+5. Dispatch the Documenter subagent via the Task tool:
+   - `subagent_type`: `general-purpose`
+   - `model`: `sonnet`
+   - Prompt: contents of `~/.claude/plugins/cloverleaf/prompts/documenter.md` with substitutions:
+     - `{{task}}` → full task JSON (pretty-printed)
+     - `{{diff}}` → diff output
+     - `{{branch}}` → `cloverleaf/<TASK-ID>`
+     - `{{base_branch}}` → `main`
+     - `{{repo_root}}` → absolute path
+
+6. Parse the subagent's response. Expect JSON of the form `{"commits_added": N, "files_changed": [...], "summary": "..."}`.
+
+7. On failure to parse or response with invalid shape: report the response and stop without advancing state.
+
+8. Advance state:
+   ```
+   cloverleaf-cli advance-status <repo_root> <TASK-ID> documenting agent
+   cloverleaf-cli advance-status <repo_root> <TASK-ID> review agent
+   ```
+
+9. Commit state changes:
+   ```bash
+   cd <repo_root>
+   git add .cloverleaf/
+   git commit -m "cloverleaf: <TASK-ID> documented → review"
+   ```
+
+10. Report:
+    - "✓ Documenter done. `<commits_added>` doc commit(s) added. State → review."
+    - "Files changed: `<comma-separated files_changed>`."
+    - "Next: `/cloverleaf-review <TASK-ID>`."
+
+## Rules
+
+- Never push.
+- Do not modify source code — Documenter is doc-only.
+- If any `advance-status` call fails, stop and report.
+- The skill's working directory is the consumer's repo root.

package/skills/cloverleaf-implement.md

@@ -45,7 +45,9 @@ The user has invoked this skill with a TASK-ID (e.g., `DEMO-001`).
 
    If this fails (uncommitted changes on main, detached HEAD, etc.), report the error and stop without advancing state.
 
-8. Run each of these CLI calls in sequence:
+8. Walk the state machine. Read `task.risk_class` (already captured at step 2).
+
+   **If `risk_class === "low"` (fast lane — v0.1.1 behavior):**
 
    If the current task status is `pending`:
    ```
@@ -61,18 +63,32 @@ The user has invoked this skill with a TASK-ID (e.g., `DEMO-001`).
    cloverleaf-cli advance-status <repo_root> <TASK-ID> review agent
    ```
 
+   **If `risk_class === "high"` (full pipeline — new in v0.2):**
+
+   If the current task status is `pending`:
+   ```
+   cloverleaf-cli advance-status <repo_root> <TASK-ID> tactical-plan agent
+   cloverleaf-cli advance-status <repo_root> <TASK-ID> implementing agent
+   ```
+   Stop here. Documenter runs next (will advance implementing → documenting → review).
+
+   If the current task status was `implementing` (loop-back after Reviewer/UI/QA bounce):
+   No state advance — the bouncing skill already moved state back to `implementing`.
+
 9. Commit the state changes:
    ```
    cd <repo_root>
    git add .cloverleaf/
-   git commit -m "cloverleaf: <TASK-ID> → review"
+   git commit -m "cloverleaf: <TASK-ID> → <new-state>"
    ```
+   where `<new-state>` is `review` for fast lane (`risk_class === "low"`) or `implementing` for full pipeline (`risk_class === "high"`).
 
 10. Report:
-    - "✓ Implementer done. Branch `<branch>`. State → review."
+    - "✓ Implementer done. Branch `<branch>`. State → <new-state>."
     - "Files changed: <comma-separated>."
     - "Currently on: `main`."
-    - "Next: `/cloverleaf-review <TASK-ID>`."
+    - **If `risk_class === "low"`:** "Next: `/cloverleaf-review <TASK-ID>`."
+    - **If `risk_class === "high"`:** "Next: `/cloverleaf-document <TASK-ID>`."
 
 ## Rules
 

package/skills/cloverleaf-merge.md

@@ -1,42 +1,70 @@
 ---
 name: cloverleaf-merge
-description: Human gate for merging a Cloverleaf task. Advances automated-gates → merged via the human_merge gate, requires explicit user confirmation. Usage — /cloverleaf-merge <TASK-ID>.
+description: Human gate for merging a Cloverleaf task. Branches on state — from `automated-gates` (fast lane) via `human_merge`, or from `final-gate` (full pipeline) via `final_approval_gate`. Requires explicit user confirmation. Usage — /cloverleaf-merge <TASK-ID>.
 ---
 
 # Cloverleaf — merge
 
 ## Steps
 
-0. Ensure you are on `main`. State is authoritative on main. Run:
-
+0. Ensure you are on `main`. Run:
    ```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 — the user must clean up first.
+   If main has uncommitted changes, stop and report.
 
 1. Capture the TASK-ID.
 
-2. Load the task: `cloverleaf-cli load-task <repo_root> <TASK-ID>`. Verify `status === "automated-gates"`. If not, report and stop.
+2. Load the task: `cloverleaf-cli load-task <repo_root> <TASK-ID>`. Let `S` = `task.status`.
+
+   - If `S === "automated-gates"`: this is a fast-lane merge. Proceed with section 3A.
+   - If `S === "final-gate"`: this is a full-pipeline merge. Proceed with section 3B.
+   - Else: report the current status and stop.
+
+### 3A. Fast-lane confirmation
+
+3A.1. Show to user:
+> "About to merge `<TASK-ID>` (fast lane). Branch `cloverleaf/<TASK-ID>` has been reviewed and passed. Confirm merge? (y/N)"
+
+3A.2. On explicit `y`:
+   - `cloverleaf-cli emit-gate-decision <repo_root> <TASK-ID> human_merge approve human`
+   - `cloverleaf-cli advance-status <repo_root> <TASK-ID> merged human human_merge fast_lane`
+   - Commit: `git add .cloverleaf/ && git commit -m "cloverleaf: <TASK-ID> merged (fast lane)"`.
+
+### 3B. Full-pipeline final approval
+
+3B.1. Collect summaries. Read the latest feedback files:
+   ```bash
+   ls <repo_root>/.cloverleaf/feedback/<TASK-ID>-*.json | sort
+   ```
+   Extract `summary` and `verdict` from each. Group by prefix:
+   - `r*.json` → Reviewer
+   - `u*.json` → UI Reviewer
+   - `q*.json` → QA
 
-3. Confirm with the user. Print:
-   > "About to merge `<TASK-ID>`. Branch `cloverleaf/<TASK-ID>` has been reviewed and passed. Confirm merge? (y/N)"
+3B.2. Show to user:
+> "About to merge `<TASK-ID>` (full pipeline). Final approval required. Summaries:
+> - Reviewer: <summary>
+> - UI Reviewer: <summary or 'not run'>
+> - QA: <summary with results>
+> Confirm merge? (y/N)"
 
-   Wait for the user's reply. Only proceed on explicit `y`, `Y`, `yes`, or `YES`. Anything else: abort without state change.
+3B.3. On explicit `y`:
+   - `cloverleaf-cli emit-gate-decision <repo_root> <TASK-ID> final_approval_gate approve human`
+   - `cloverleaf-cli advance-status <repo_root> <TASK-ID> merged human final_approval_gate full_pipeline`
+   - Commit: `git add .cloverleaf/ && git commit -m "cloverleaf: <TASK-ID> merged (full pipeline)"`.
 
-4. On confirmation:
-   - Emit the gate decision: `cloverleaf-cli emit-gate-decision <repo_root> <TASK-ID> human_merge approve human`. Note: decision is `approve` (not `approved` — per the gate-decision schema's enum).
-   - Advance: `cloverleaf-cli advance-status <repo_root> <TASK-ID> merged human human_merge fast_lane`.
-   - Commit state: `git add .cloverleaf/ && git commit -m "cloverleaf: <TASK-ID> merged"`.
+### 4. Common: report
 
-5. Report:
-   - "✓ Merged `<TASK-ID>`. Branch `cloverleaf/<TASK-ID>` is ready for you to push and open a PR."
-   - "Suggested: `git push origin cloverleaf/<TASK-ID>` then open a PR against `main`."
+Report:
+- "✓ Merged `<TASK-ID>`. Branch `cloverleaf/<TASK-ID>` is ready for you to push and open a PR."
+- "Suggested: `git push origin cloverleaf/<TASK-ID>` then open a PR against `main`."
 
 ## Rules
 
-- The skill does NOT push the branch or open a PR. That remains explicit to the user.
-- The `merged` status in `.cloverleaf/` is the Cloverleaf-level record; the actual GitHub merge is the user's responsibility.
+- Only proceed on explicit `y`, `Y`, `yes`, `YES`. Anything else: abort without state change.
+- The skill does NOT push the branch or open a PR.
+- Fast lane and full pipeline use distinct gates — the state machine records which path was taken.
 - If the user declines, no state change and no commit.

package/skills/cloverleaf-new-task.md

@@ -53,4 +53,12 @@ The user has invoked this skill with a brief. Your job: turn the brief into a st
 ## Rules
 
 - Do not guess at acceptance criteria. If the brief is too vague (e.g., "make it faster" with no target), ask the user a clarifying question before writing the file.
-- If the user's brief hints at complex/risky work (UI changes, breaking API, cross-project), set `risk_class: "high"` and mention it. Default is `"low"` for simple tasks.
+- **risk_class inference:** `risk_class` determines the Delivery pipeline (`"low"` → fast lane; `"high"` → full pipeline). Rules:
+  1. If the user passed `--risk=high` or `--risk=low` as a flag on the skill invocation, honor it.
+  2. Otherwise, set `risk_class: "high"` when the brief OR any acceptance criterion matches (case-insensitive) any of these keywords:
+     `site/`, `UI`, `page`, `component`, `style`, `visual`, `layout`, `render`, `display`, `accessibility`, `a11y`, `responsive`, `.astro`, `.css`, `.html`
+  3. Also set `risk_class: "high"` for breaking APIs or cross-project work (v0.1.1 behavior, retained).
+  4. Default: `risk_class: "low"`.
+- After writing the task, report the chosen risk_class and how it was determined, e.g.:
+  > "Risk class: `high` → full pipeline (matched keyword `component` in acceptance criterion). Override with `--risk=low` if desired."
+- Users can manually edit `risk_class` in the task JSON before running `/cloverleaf-run`.

package/skills/cloverleaf-qa.md

@@ -0,0 +1,64 @@
+---
+name: cloverleaf-qa
+description: Run the QA agent on a task in the `qa` state (full pipeline only). Dispatches a subagent to run per-package test suites against an isolated worktree; emits feedback envelope with results; advances qa → final-gate on pass or loops back to implementing on bounce. Usage — /cloverleaf-qa <TASK-ID>.
+---
+
+# Cloverleaf — qa
+
+## Steps
+
+0. Ensure you are on `main`. If not, `git checkout main`. If main has uncommitted changes, stop and report.
+
+1. Capture the TASK-ID argument.
+
+2. Load the task:
+   ```
+   cloverleaf-cli load-task <repo_root> <TASK-ID>
+   ```
+   Verify `status === "qa"`. If not, report and stop.
+
+3. Confirm feature branch exists: `git rev-parse --verify cloverleaf/<TASK-ID>`.
+
+4. Load QA rules JSON:
+   ```bash
+   cat ~/.claude/plugins/cloverleaf/config/qa-rules.json
+   ```
+   Capture for the subagent as `qa_rules`.
+
+5. Compute diff:
+   ```bash
+   git diff main..cloverleaf/<TASK-ID>
+   ```
+
+6. Dispatch the QA subagent via the Task tool:
+   - `subagent_type`: `general-purpose`
+   - `model`: `sonnet`
+   - Prompt: contents of `~/.claude/plugins/cloverleaf/prompts/qa.md` with substitutions for `{{task}}`, `{{diff}}`, `{{branch}}`, `{{base_branch}}`, `{{repo_root}}`, `{{qa_rules}}` (the JSON loaded in step 4).
+
+7. Parse response: expect `{"verdict": "pass"|"bounce"|"escalate", "summary", "findings", "results"}`.
+
+8. Branch on verdict:
+
+   **Pass:**
+   ```
+   cloverleaf-cli advance-status <repo_root> <TASK-ID> final-gate agent --path=full_pipeline
+   ```
+   Commit: `git add .cloverleaf/ && git commit -m "cloverleaf: <TASK-ID> qa passed → final-gate"`.
+   Report: "✓ QA passed (`<passed>/<total>` tests). State → final-gate. Next: `/cloverleaf-merge <TASK-ID>`."
+
+   **Bounce:**
+   1. Write feedback envelope: `echo '<json>' > /tmp/cloverleaf-fb-q.json`
+   2. `cloverleaf-cli write-feedback <repo_root> <TASK-ID> /tmp/cloverleaf-fb-q.json --prefix=q`
+   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> qa bounced → implementing"`.
+   5. Report: "✗ QA bounced. `<failed>/<total>` tests failed. 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> qa escalated"`.
+   3. Report: "✗ QA escalated. Review infrastructure and retry manually."
+
+## Rules
+
+- Never push. Read-only. Do not modify source.
+- On illegal state transition, report and stop.

package/skills/cloverleaf-run.md

@@ -1,41 +1,95 @@
 ---
 name: cloverleaf-run
-description: End-to-end orchestrator. Loops implement → review → (bounce ↻ implement) → pause at human merge gate. Max 3 bounces before escalation. Usage — /cloverleaf-run <TASK-ID>.
+description: End-to-end orchestrator. Reads task.risk_class to dispatch fast lane (implement → review → merge) or full pipeline (implement → document → review → [ui-review?] → qa → final-merge). Per-agent bounce counters (max 3 each). Usage — /cloverleaf-run <TASK-ID>.
 ---
 
 # Cloverleaf — run (orchestrator)
 
 ## Branch discipline
 
-The orchestrator runs each sub-skill with the assumption that the working tree starts on `main`. Between steps, confirm the branch is main before proceeding. The Implementer step leaves the user on main after its internal `git checkout main`; the Reviewer and Merge steps start on main.
+Each sub-skill runs from `main`. Between steps, confirm branch is `main` before proceeding. All sub-skills return the user to `main`.
+
+## Per-agent bounce budget
+
+```
+MAX_REVIEWER_BOUNCES    = 3
+MAX_UI_REVIEWER_BOUNCES = 3
+MAX_QA_BOUNCES          = 3
+```
+
+These counters live in-session (not persisted). Rerunning `/cloverleaf-run` resets.
 
 ## Steps
 
-1. Capture the TASK-ID.
+1. Capture TASK-ID.
+
+2. Load task: `cloverleaf-cli load-task <repo_root> <TASK-ID>`. Verify `status === "pending"`. If not, report and stop.
+
+3. Read `task.risk_class`:
+   - `"low"` → go to section 4 (Fast Lane)
+   - `"high"` → go to section 5 (Full Pipeline)
+
+### 4. Fast Lane
+
+Initialize `reviewer_bounces = 0`.
+
+Loop:
+  a. Inline `/cloverleaf-implement <TASK-ID>` steps.
+  b. Inline `/cloverleaf-review <TASK-ID>` steps.
+  c. Reload task. If `status === "automated-gates"`: pass! Break loop.
+  d. If `status === "implementing"`: Reviewer bounced. `reviewer_bounces += 1`. If `reviewer_bounces >= MAX_REVIEWER_BOUNCES`, escalate (section 6). Else continue loop.
+  e. Else: unexpected state. Report and stop.
+
+After loop: inline `/cloverleaf-merge <TASK-ID>`.
+
+### 5. Full Pipeline
+
+Initialize `reviewer_bounces = 0`, `ui_reviewer_bounces = 0`, `qa_bounces = 0`.
+
+5.1. **Implementer → Documenter → Reviewer loop:**
+
+Loop:
+  a. Inline `/cloverleaf-implement <TASK-ID>` steps.
+  b. Inline `/cloverleaf-document <TASK-ID>` steps.
+  c. Inline `/cloverleaf-review <TASK-ID>` steps.
+  d. Reload task. If `status === "automated-gates"`: pass! Exit this loop.
+  e. If `status === "implementing"`: Reviewer bounced. `reviewer_bounces += 1`. If `reviewer_bounces >= MAX_REVIEWER_BOUNCES`, escalate. Else continue loop.
+  f. Else: unexpected. Report and stop.
 
-2. Load the task: `cloverleaf-cli load-task <repo_root> <TASK-ID>`. Verify `status === "pending"`. If not, report and stop — suggest the user run individual skills instead.
+5.2. **UI-path detection and conditional UI Review:**
 
-3. Loop, up to `MAX_BOUNCES = 3`:
+```bash
+cloverleaf-cli detect-ui-paths <repo_root> <TASK-ID>
+```
 
-   a. Invoke `/cloverleaf-implement <TASK-ID>` (inline the steps from that skill — do not actually call the slash command recursively).
+If output is `true`:
+  - Advance: `cloverleaf-cli advance-status <repo_root> <TASK-ID> ui-review agent --path=full_pipeline`. Commit.
+  - UI-review loop:
+    a. Inline `/cloverleaf-ui-review <TASK-ID>` steps.
+    b. Reload task. If `status === "qa"`: pass! Exit UI-review loop.
+    c. If `status === "implementing"`: UI Reviewer bounced. `ui_reviewer_bounces += 1`. If `>= MAX_UI_REVIEWER_BOUNCES`, escalate. Else return to section 5.1 (Implementer re-runs, which then re-documents, re-reviews).
+    d. Else: unexpected. Report and stop.
 
-   b. Invoke `/cloverleaf-review <TASK-ID>`.
+If output is `false`: skip UI review. Advance: `cloverleaf-cli advance-status <repo_root> <TASK-ID> qa agent --path=full_pipeline`. Commit.
 
-   c. Re-load the task. If `status === "automated-gates"` — pass! Break out of the loop.
+5.3. **QA loop:**
 
-   d. Else if `status === "implementing"` — bounce. Increment bounce counter. If counter == MAX_BOUNCES, escalate (step 5) and stop.
+Loop:
+  a. Inline `/cloverleaf-qa <TASK-ID>` steps.
+  b. Reload task. If `status === "final-gate"`: pass! Exit loop.
+  c. If `status === "implementing"`: QA bounced. `qa_bounces += 1`. If `qa_bounces >= MAX_QA_BOUNCES`, escalate. Else return to section 5.1.
+  d. Else: unexpected. Report and stop.
 
-   e. Else — unexpected state. Report and stop.
+5.4. **Final merge:** Inline `/cloverleaf-merge <TASK-ID>` steps (branches to full-pipeline gate per state).
 
-4. On pass: invoke `/cloverleaf-merge <TASK-ID>`, which prompts the user for confirmation.
+### 6. Escalation
 
-5. On max bounces exceeded:
-   - `cloverleaf-cli advance-status <repo_root> <TASK-ID> escalated agent`.
-   - Commit: `git add .cloverleaf/ && git commit -m "cloverleaf: <TASK-ID> escalated after 3 bounces"`.
-   - Report: "✗ Escalated `<TASK-ID>` after 3 bounces. Review the feedback files under `.cloverleaf/feedback/` and either refine the task or take over manually."
+- `cloverleaf-cli advance-status <repo_root> <TASK-ID> escalated agent`
+- Commit: `git add .cloverleaf/ && git commit -m "cloverleaf: <TASK-ID> escalated (bounce budget exhausted)"`.
+- Report: "✗ Escalated `<TASK-ID>`. Review `.cloverleaf/feedback/` and either refine the task or take over manually. Counters: reviewer=<N>, ui_reviewer=<N>, qa=<N>."
 
 ## Rules
 
-- MAX_BOUNCES is hardcoded to 3 for v0.1.0.
-- The orchestrator does not skip the human_merge gate; the user's confirmation is still required at merge time.
-- If ANY individual skill reports an error or stops, the orchestrator also stops with a clear message.
+- Each agent has its own 3-bounce budget. Bounces from different agents do NOT share counters.
+- On any sub-skill error or escalation, orchestrator stops with clear message.
+- Human merge gate is NOT skipped; confirmation is still required at merge time.

package/skills/cloverleaf-ui-review.md

@@ -0,0 +1,73 @@
+---
+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>.
+---
+
+# Cloverleaf — ui-review
+
+## Steps
+
+0. Ensure you are on `main`. State is authoritative on main. Run:
+
+   ```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:
+   ```
+   ~/.claude/plugins/cloverleaf/bin/cloverleaf-cli load-task <repo_root> <TASK-ID>
+   ```
+   Verify `status === "ui-review"`. If not, report and stop.
+
+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:
+   ```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:
+   ```bash
+   git diff main..cloverleaf/<TASK-ID>
+   ```
+
+6. 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}}`.
+
+7. Parse the subagent's response. Expect `{"verdict": "pass"|"bounce"|"escalate", "summary": "...", "findings": [...]}`.
+
+8. 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>`."
+
+   **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>`."
+
+   **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.
+- On illegal state transition, report and stop without partial commits.