@cloverleaf/reference-impl 0.1.1 → 0.3.0

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,103 @@
+# 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)
+- **Affected routes**: {{affected_routes}} — either a JSON array of route paths (e.g., `["/faq/"]`), or the string `"all"`, or `[]`
+
+## Scope (v0.3)
+
+- Accessibility only (axe-core). No visual diff, no responsive checks.
+- Single viewport: 1280×800.
+- Run axe ONLY on the pages listed in `{{affected_routes}}`.
+  - If `{{affected_routes}}` is `"all"`: crawl up to 20 pages reachable from `/` via same-origin link discovery (v0.2 fallback behavior).
+  - If `{{affected_routes}}` is `[]`: return `verdict: "pass"` with summary "No renderable routes affected, skipping axe." Do NOT start the preview server.
+  - Otherwise: visit exactly the URLs listed. No link-discovery crawl.
+- Visual diff, viewports loop, and `visual_diff_uri` are deferred to v0.4.
+
+## Playwright cache
+
+The `PLAYWRIGHT_BROWSERS_PATH` environment variable is set to `~/.cache/ms-playwright` before you are invoked. Playwright resolves chromium from this shared cache, so `npm ci` in the worktree does NOT re-download ~300 MB of browser binaries. If the browser is missing, return `verdict: "escalate"` with a synthetic finding: `"Playwright chromium not installed. Run 'npx playwright install chromium' on this machine."`
+
+## Runtime procedure
+
+1. If `{{affected_routes}}` is `[]`, return immediately (pass-skip) — no worktree, no server, no browser.
+
+2. Set up an isolated worktree of the feature branch:
+   ```bash
+   TMPDIR=$(mktemp -d)
+   git worktree add "$TMPDIR" {{branch}}
+   ```
+
+3. 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=$!
+   ```
+
+4. Wait up to 30s for `http://localhost:{{preview_port}}/` to respond 200. If the server fails to start in 30s, kill it and return verdict `escalate`.
+
+5. Determine the site base path: read `astro.config.*` in the worktree for a `base: '<path>'` entry. Default to empty string if not found or unparseable.
+
+6. For each route in `{{affected_routes}}` (or the crawl set, if `"all"`):
+   - Construct URL `http://localhost:{{preview_port}}<base><route>`.
+   - Navigate. If 404, retry at `http://localhost:{{preview_port}}<route>` (without base).
+   - Inject and run axe-core:
+     ```javascript
+     import axe from 'axe-core';
+     const results = await axe.run(document);
+     ```
+   - Collect violations.
+
+7. Map violations to findings:
+   - axe `impact: "critical"` → `severity: "blocker"`
+   - axe `impact: "serious"` → `severity: "error"`
+   - axe `impact: "moderate"` → `severity: "warning"`
+   - axe `impact: "minor"` → `severity: "info"`
+
+8. Compute verdict:
+   - `pass` — zero findings with severity `blocker` or `error`
+   - `bounce` — ≥1 finding with severity `blocker` or `error`
+   - `escalate` — preview server failed to start, OR axe threw ≥3 consecutive times, OR Playwright chromium missing.
+
+9. 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).

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.