@cloverleaf/reference-impl 0.3.1 → 0.4.1

package/skills/{cloverleaf-document.md → cloverleaf-document/SKILL.md}

@@ -21,7 +21,7 @@ description: Run the Documenter agent on a task in the `implementing` state (ful
 
 2. Load the task:
    ```
-   ~/.claude/plugins/cloverleaf/bin/cloverleaf-cli load-task <repo_root> <TASK-ID>
+   cloverleaf-cli load-task <repo_root> <TASK-ID>
    ```
    Verify `status === "implementing"`. Verify `risk_class === "high"`. If either check fails, report and stop.
 
@@ -36,7 +36,7 @@ description: Run the Documenter agent on a task in the `implementing` state (ful
 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:
+   - Prompt: contents of `$(cloverleaf-cli plugin-root)/prompts/documenter.md` with substitutions:
      - `{{task}}` → full task JSON (pretty-printed)
      - `{{diff}}` → diff output
      - `{{branch}}` → `cloverleaf/<TASK-ID>`

package/skills/{cloverleaf-implement.md → cloverleaf-implement/SKILL.md}

@@ -13,20 +13,20 @@ The user has invoked this skill with a TASK-ID (e.g., `DEMO-001`).
 
 2. Load the task:
    ```
-   ~/.claude/plugins/cloverleaf/bin/cloverleaf-cli load-task <repo_root> <TASK-ID>
+   cloverleaf-cli load-task <repo_root> <TASK-ID>
    ```
    Parse the JSON. Verify `status === "pending"` OR `status === "implementing"` (the second case is a re-run after a Reviewer bounce). If neither, report the current status and ask the user to use the correct command for that state.
 
 3. Load any outstanding feedback:
    ```
-   ~/.claude/plugins/cloverleaf/bin/cloverleaf-cli latest-feedback <repo_root> <TASK-ID>
+   cloverleaf-cli latest-feedback <repo_root> <TASK-ID>
    ```
    Capture the output. If present and the latest verdict is `bounce`, pass it into the subagent.
 
 4. Dispatch the Implementer subagent via the Task tool:
    - `subagent_type`: `general-purpose`
    - `model`: `sonnet`
-   - Prompt: the contents of `~/.claude/plugins/cloverleaf/prompts/implementer.md`, with placeholders substituted:
+   - Prompt: the contents of `$(cloverleaf-cli plugin-root)/prompts/implementer.md`, with placeholders substituted:
      - `{{task}}` → the full task JSON (pretty-printed)
      - `{{feedback}}` → the feedback JSON if present, else the literal string `null`
      - `{{repo_root}}` → absolute path to the current repo

package/skills/{cloverleaf-merge.md → cloverleaf-merge/SKILL.md}

@@ -1,6 +1,6 @@
 ---
 name: cloverleaf-merge
-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>.
+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`. For full-pipeline tasks, performs a real `git merge --no-ff` of the feature branch into main before advancing state. Requires explicit user confirmation. Usage — /cloverleaf-merge <TASK-ID>.
 ---
 
 # Cloverleaf — merge
@@ -53,18 +53,39 @@ description: Human gate for merging a Cloverleaf task. Branches on state — fro
 
 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)"`.
+   - Verify we are on main with a clean working tree:
+     ```bash
+     cd <repo_root>
+     git checkout main
+     git status
+     # must be clean
+     ```
+     If not clean, stop and report.
+   - Perform the real merge — brings the feature branch's Implementer commit, ui-review baseline commit, and any feedback commits into main:
+     ```bash
+     git merge --no-ff cloverleaf/${TASK_ID} -m "cloverleaf: ${TASK_ID} merged (full pipeline)"
+     ```
+     If git reports conflicts: abort and escalate.
+     ```bash
+     git merge --abort
+     cloverleaf-cli advance-status <repo_root> ${TASK_ID} escalated agent
+     ```
+     Exit with a human-readable error explaining the conflict.
+   - Advance task status on main (commits `.cloverleaf/tasks/${TASK_ID}.json` + event):
+     ```bash
+     cloverleaf-cli advance-status <repo_root> ${TASK_ID} merged agent
+     ```
 
 ### 4. Common: report
 
 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`."
+- "✓ Merged `<TASK-ID>`. Branch `cloverleaf/<TASK-ID>` has been merged into main."
+- "Suggested: `git push origin main` to push the merge commit."
 
 ## Rules
 
 - 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.
+- Full-pipeline merges perform a real `git merge --no-ff` before advancing state — the feature branch's code, baselines, and feedback commits all land on main.
 - If the user declines, no state change and no commit.

package/skills/{cloverleaf-new-task.md → cloverleaf-new-task/SKILL.md}

@@ -11,13 +11,13 @@ The user has invoked this skill with a brief. Your job: turn the brief into a st
 
 1. Determine the active project. Run:
    ```
-   ~/.claude/plugins/cloverleaf/bin/cloverleaf-cli infer-project <repo_root>
+   cloverleaf-cli infer-project <repo_root>
    ```
    where `<repo_root>` is the current working directory. On failure (no projects, or multiple projects), report the error and ask the user to specify `--project=<id>` or to create a project config first.
 
 2. Allocate the next task ID:
    ```
-   ~/.claude/plugins/cloverleaf/bin/cloverleaf-cli next-task-id <repo_root> --project=<project>
+   cloverleaf-cli next-task-id <repo_root> --project=<project>
    ```
    Capture the output (e.g., `DEMO-002`).
 
@@ -45,7 +45,19 @@ The user has invoked this skill with a brief. Your job: turn the brief into a st
 
 6. Commit: `git add .cloverleaf/tasks/<allocated-id>.json && git commit -m "cloverleaf: task <allocated-id>"`.
 
-7. Report:
+7. **v0.4 scaffolding:** Ensure baseline and run directories are set up:
+   ```bash
+   # v0.4 scaffolding additions — baselines tracked, runs ephemeral
+   mkdir -p <repo_root>/.cloverleaf/baselines
+   mkdir -p <repo_root>/.cloverleaf/runs
+   
+   # Ensure .gitignore excludes runs/ (baselines ARE tracked, only runs is ephemeral)
+   if ! grep -qE '^\.cloverleaf/runs/?$' <repo_root>/.gitignore 2>/dev/null; then
+     echo '.cloverleaf/runs/' >> <repo_root>/.gitignore
+   fi
+   ```
+
+8. Report:
    - "Created `<allocated-id>` at `.cloverleaf/tasks/<allocated-id>.json`."
    - Show the generated acceptance criteria.
    - Suggest: "Review and edit the task if needed, then run `/cloverleaf-run <allocated-id>`."
@@ -62,3 +74,8 @@ The user has invoked this skill with a brief. Your job: turn the brief into a st
 - 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`.
+
+## v0.4 artifacts
+
+- `.cloverleaf/baselines/` is **tracked** in git; baseline PNGs travel with code.
+- `.cloverleaf/runs/` is **gitignored**; each task's run artifacts (diffs, candidate screenshots, QA reports) are ephemeral.

package/skills/{cloverleaf-qa.md → cloverleaf-qa/SKILL.md}

@@ -7,7 +7,11 @@ description: Run the QA agent on a task in the `qa` state (full pipeline only).
 
 ## Steps
 
-0. Ensure you are on `main`. If not, `git checkout main`. If main has uncommitted changes, stop and report.
+0. Pre-flight: ensure you are on `main` and clean stale feedback temp files from previous runs (prevents /tmp leakage between tasks). If not on main, `git checkout main`. If main has uncommitted changes, stop and report.
+
+   ```bash
+   rm -f /tmp/cloverleaf-fb-r.json /tmp/cloverleaf-fb-u.json /tmp/cloverleaf-fb-q.json
+   ```
 
 1. Capture the TASK-ID argument.
 
@@ -19,30 +23,35 @@ description: Run the QA agent on a task in the `qa` state (full pipeline only).
 
 3. Confirm feature branch exists: `git rev-parse --verify cloverleaf/<TASK-ID>`.
 
-4. Load QA rules JSON:
+4. Ensure required directories exist:
+   ```bash
+   mkdir -p <repo_root>/.cloverleaf/runs/<TASK-ID>/qa
+   ```
+
+5. Load QA rules JSON:
    ```bash
    # Consumer override takes precedence over the package default.
    if [ -f "<repo_root>/.cloverleaf/config/qa-rules.json" ]; then
      cat "<repo_root>/.cloverleaf/config/qa-rules.json"
    else
-     cat ~/.claude/plugins/cloverleaf/config/qa-rules.json
+     cat $(cloverleaf-cli plugin-root)/config/qa-rules.json
    fi
    ```
    Capture for the subagent as `qa_rules`.
 
-5. Compute diff:
+6. Compute diff:
    ```bash
    git diff main..cloverleaf/<TASK-ID>
    ```
 
-6. Dispatch the QA subagent via the Task tool:
+7. 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).
+   - Prompt: contents of `$(cloverleaf-cli plugin-root)/prompts/qa.md` with substitutions for `{{task}}`, `{{diff}}`, `{{branch}}`, `{{base_branch}}`, `{{repo_root}}`, `{{qa_rules}}` (the JSON loaded in step 5).
 
-7. Parse response: expect `{"verdict": "pass"|"bounce"|"escalate", "summary", "findings", "results"}`.
+8. Parse response: expect `{"verdict": "pass"|"bounce"|"escalate", "summary", "findings", "results"}`.
 
-8. Branch on verdict:
+9. Branch on verdict:
 
    **Pass:**
    ```
@@ -54,9 +63,15 @@ description: Run the QA agent on a task in the `qa` state (full pipeline only).
    **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>`."
+   3. Commit the persisted feedback file (was missing pre-v0.4.1 — bug #3):
+      ```bash
+      cd <repo_root>
+      git add .cloverleaf/feedback/
+      git commit -m "cloverleaf: <TASK-ID> qa feedback"
+      ```
+   4. `cloverleaf-cli advance-status <repo_root> <TASK-ID> implementing agent --path=full_pipeline`
+   5. Commit: `git add .cloverleaf/ && git commit -m "cloverleaf: <TASK-ID> qa bounced → implementing"`.
+   6. 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`

package/skills/{cloverleaf-review.md → cloverleaf-review/SKILL.md}

@@ -7,7 +7,7 @@ description: Run the Reviewer agent on a task in the `review` state. Emits a fee
 
 ## Steps
 
-0. Ensure you are on `main`. State is authoritative on main. Run:
+0. Pre-flight: ensure you are on `main` and clean stale feedback temp files from previous runs (prevents /tmp leakage between tasks):
 
    ```bash
    cd <repo_root>
@@ -17,11 +17,15 @@ description: Run the Reviewer agent on a task in the `review` state. Emits a fee
 
    If main has uncommitted changes, stop and report — the user must clean up first.
 
+   ```bash
+   rm -f /tmp/cloverleaf-fb-r.json /tmp/cloverleaf-fb-u.json /tmp/cloverleaf-fb-q.json
+   ```
+
 1. Capture the TASK-ID argument.
 
 2. Load the task:
    ```
-   ~/.claude/plugins/cloverleaf/bin/cloverleaf-cli load-task <repo_root> <TASK-ID>
+   cloverleaf-cli load-task <repo_root> <TASK-ID>
    ```
    Verify `status === "review"`. If not, report the current status and stop.
 
@@ -36,7 +40,7 @@ description: Run the Reviewer agent on a task in the `review` state. Emits a fee
 5. Dispatch the Reviewer subagent via the Task tool:
    - `subagent_type`: `general-purpose`
    - `model`: `sonnet`
-   - Prompt: contents of `~/.claude/plugins/cloverleaf/prompts/reviewer.md` with substitutions for `{{task}}`, `{{branch}}`, `{{base_branch}}`, `{{repo_root}}`, `{{diff}}`.
+   - Prompt: contents of `$(cloverleaf-cli plugin-root)/prompts/reviewer.md` with substitutions for `{{task}}`, `{{branch}}`, `{{base_branch}}`, `{{repo_root}}`, `{{diff}}`.
 
 6. Parse the subagent's response. Expect a feedback envelope JSON of the form `{"verdict": "pass"|"bounce", "summary": "...", "findings": [...]}`. Validate shape: verdict must be `pass` or `bounce`; if `bounce`, findings must have at least one entry with `severity` (one of `blocker|error|warning|info`) and `message`.
 
@@ -50,11 +54,17 @@ description: Run the Reviewer agent on a task in the `review` state. Emits a fee
    Report: "✓ Review passed. State → automated-gates. Next: `/cloverleaf-merge <TASK-ID>`."
 
    **Bounce:**
-   1. Write the feedback envelope to a temp file: `echo '<envelope-json>' > /tmp/cloverleaf-fb.json`.
-   2. `cloverleaf-cli write-feedback <repo_root> <TASK-ID> /tmp/cloverleaf-fb.json` — captures the path like `.cloverleaf/feedback/<TASK-ID>-r<N>.json`.
-   3. `cloverleaf-cli advance-status <repo_root> <TASK-ID> implementing agent` — loops back.
-   4. Commit: `git add .cloverleaf/ && git commit -m "cloverleaf: <TASK-ID> review bounced → implementing"`.
-   5. Report: "✗ Review bounced. Findings: <summarize findings by severity>. State → implementing. Next: `/cloverleaf-implement <TASK-ID>`."
+   1. Write the feedback envelope to a temp file: `echo '<envelope-json>' > /tmp/cloverleaf-fb-r.json`.
+   2. `cloverleaf-cli write-feedback <repo_root> <TASK-ID> /tmp/cloverleaf-fb-r.json` — captures the path like `.cloverleaf/feedback/<TASK-ID>-r<N>.json`.
+   3. Commit the persisted feedback file (was missing pre-v0.4.1 — bug #3):
+      ```bash
+      cd <repo_root>
+      git add .cloverleaf/feedback/
+      git commit -m "cloverleaf: <TASK-ID> review feedback"
+      ```
+   4. `cloverleaf-cli advance-status <repo_root> <TASK-ID> implementing agent` — loops back.
+   5. Commit: `git add .cloverleaf/ && git commit -m "cloverleaf: <TASK-ID> review bounced → implementing"`.
+   6. Report: "✗ Review bounced. Findings: <summarize findings by severity>. State → implementing. Next: `/cloverleaf-implement <TASK-ID>`."
 
 ## Rules
 

package/skills/{cloverleaf-ui-review.md → cloverleaf-ui-review/SKILL.md}

@@ -7,7 +7,7 @@ description: Run the UI Reviewer agent on a task in the `ui-review` state (full
 
 ## Steps
 
-0. Ensure you are on `main`. State is authoritative on main. Run:
+0. Pre-flight: ensure you are on `main` and clean stale feedback temp files from previous runs (prevents /tmp leakage between tasks):
 
    ```bash
    cd <repo_root>
@@ -17,22 +17,32 @@ description: Run the UI Reviewer agent on a task in the `ui-review` state (full
 
    If main has uncommitted changes, stop and report.
 
+   ```bash
+   rm -f /tmp/cloverleaf-fb-r.json /tmp/cloverleaf-fb-u.json /tmp/cloverleaf-fb-q.json
+   ```
+
 1. Capture the TASK-ID argument.
 
 2. Load the task:
    ```
-   ~/.claude/plugins/cloverleaf/bin/cloverleaf-cli load-task <repo_root> <TASK-ID>
+   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. Compute affected routes:
+4. Ensure required directories exist:
+   ```bash
+   mkdir -p <repo_root>/.cloverleaf/baselines
+   mkdir -p <repo_root>/.cloverleaf/runs/<TASK-ID>/ui-review
+   ```
+
+5. Compute affected routes:
    ```bash
-   AFFECTED=$(~/.claude/plugins/cloverleaf/bin/cloverleaf-cli affected-routes <repo_root> <TASK-ID>)
+   AFFECTED=$(cloverleaf-cli affected-routes <repo_root> <TASK-ID>)
    ```
 
-5. **Empty-set early-exit.** If `AFFECTED` is `[]`, skip the subagent entirely:
+6. **Empty-set early-exit.** If `AFFECTED` is `[]`, skip the subagent entirely:
    ```bash
    cloverleaf-cli advance-status <repo_root> <TASK-ID> qa agent '' full_pipeline
    cd <repo_root>
@@ -42,28 +52,29 @@ description: Run the UI Reviewer agent on a task in the `ui-review` state (full
    Report: "✓ UI Review skipped (no renderable routes affected). State → qa. Next: `/cloverleaf-qa <TASK-ID>`."
    Stop here.
 
-6. Allocate a free preview port:
+7. Allocate a free preview port:
    ```bash
    PREVIEW_PORT=$(node -e "const net=require('net');const s=net.createServer();s.listen(0,()=>{console.log(s.address().port);s.close()})")
    ```
 
-7. Compute diff:
+8. Compute diff:
    ```bash
    git diff main..cloverleaf/<TASK-ID>
    ```
 
-8. **Browser cache env var.** Before the Task-tool dispatch, ensure `PLAYWRIGHT_BROWSERS_PATH=~/.cache/ms-playwright` is exported so the subagent inherits it. This keeps Playwright from re-downloading ~300 MB of browser binaries inside the worktree.
+9. **Browser cache env var.** Before the Task-tool dispatch, ensure `PLAYWRIGHT_BROWSERS_PATH=~/.cache/ms-playwright` is exported so the subagent inherits it. This keeps Playwright from re-downloading ~300 MB of browser binaries inside the worktree.
 
-9. 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:
-     - `{{task}}`, `{{diff}}`, `{{branch}}`, `{{base_branch}}`, `{{repo_root}}`, `{{preview_port}}`
-     - `{{affected_routes}}` → the value of `$AFFECTED` (verbatim — may be `"all"`, a JSON array, or `[]` but step 5 handled `[]` already)
+10. Dispatch the UI Reviewer subagent via the Task tool:
+    - `subagent_type`: `general-purpose`
+    - `model`: `sonnet`
+    - Prompt: contents of `$(cloverleaf-cli plugin-root)/prompts/ui-reviewer.md` with substitutions:
+      - `{{task}}`, `{{diff}}`, `{{branch}}`, `{{base_branch}}`, `{{repo_root}}`, `{{preview_port}}`
+      - `{{affected_routes}}` → the value of `$AFFECTED` (verbatim — may be `"all"`, a JSON array, or `[]` but step 6 handled `[]` already)
+      - `{{ui_review_config}}` → JSON-stringified result of `cloverleaf-cli ui-review-config <repo_root>` (used by the subagent to scope viewport sizes, thresholds, and axe rule overrides)
 
-10. Parse the subagent's response. Expect `{"verdict": "pass"|"bounce"|"escalate", "summary": "...", "findings": [...]}`.
+11. Parse the subagent's response. Expect `{"verdict": "pass"|"bounce"|"escalate", "summary": "...", "findings": [...]}`.
 
-11. Branch on verdict:
+12. Branch on verdict:
 
     **Pass:**
     ```
@@ -75,9 +86,15 @@ description: Run the UI Reviewer agent on a task in the `ui-review` state (full
     **Bounce:**
     1. Write feedback: `echo '<envelope-json>' > /tmp/cloverleaf-fb-u.json`
     2. `cloverleaf-cli write-feedback <repo_root> <TASK-ID> /tmp/cloverleaf-fb-u.json --prefix=u`
-    3. `cloverleaf-cli advance-status <repo_root> <TASK-ID> implementing agent '' full_pipeline`
-    4. Commit: `git add .cloverleaf/ && git commit -m "cloverleaf: <TASK-ID> ui-review bounced → implementing"`.
-    5. Report: "✗ UI Review bounced. Findings: <summary by severity>. State → implementing. Next: `/cloverleaf-implement <TASK-ID>`."
+    3. Commit the persisted feedback file (was missing pre-v0.4.1 — bug #3):
+       ```bash
+       cd <repo_root>
+       git add .cloverleaf/feedback/
+       git commit -m "cloverleaf: <TASK-ID> ui-review feedback"
+       ```
+    4. `cloverleaf-cli advance-status <repo_root> <TASK-ID> implementing agent '' full_pipeline`
+    5. Commit: `git add .cloverleaf/ && git commit -m "cloverleaf: <TASK-ID> ui-review bounced → implementing"`.
+    6. Report: "✗ UI Review bounced. Findings: <summary by severity>. State → implementing. Next: `/cloverleaf-implement <TASK-ID>`."
 
     **Escalate:**
     1. `cloverleaf-cli advance-status <repo_root> <TASK-ID> escalated agent`
@@ -89,5 +106,5 @@ description: Run the UI Reviewer agent on a task in the `ui-review` state (full
 - Never push.
 - Do not modify source code — UI Reviewer is read-only.
 - Always teardown preview server + worktree on error.
-- Empty-set early-exit (step 5) skips the browser entirely — no Playwright invocation, no worktree.
+- Empty-set early-exit (step 6) skips the browser entirely — no Playwright invocation, no worktree.
 - On illegal state transition, report and stop without partial commits.