@cloverleaf/reference-impl 0.4.0 → 0.4.1

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.4.0",
+  "version": "0.4.1",
   "author": {
     "name": "Renato D'Arrigo",
     "email": "renato.darrigo@gmail.com"

package/VERSION

@@ -1 +1 @@
-0.4.0
+0.4.1

package/config/ui-review.json

@@ -12,6 +12,7 @@
   },
   "axe": {
     "viewports": ["desktop"],
-    "dedupeBy": ["ruleId", "target"]
+    "dedupeBy": ["ruleId", "target"],
+    "ignored": []
   }
 }

package/dist/axe-dedupe.mjs

@@ -7,9 +7,13 @@ const SEVERITY_MAP = {
 function dedupeKeyOf(raw, keys) {
     return keys.map((k) => raw[k]).join('||');
 }
-export function dedupeAxeFindings(raws, keys) {
+export function dedupeAxeFindings(raws, keys, ignored = []) {
+    // Filter out ignored (ruleId, target) tuples BEFORE grouping.
+    const filtered = raws.filter((raw) => {
+        return !ignored.some((i) => i.ruleId === raw.ruleId && i.target === raw.target);
+    });
     const groups = new Map();
-    for (const raw of raws) {
+    for (const raw of filtered) {
         const key = dedupeKeyOf(raw, keys);
         const existing = groups.get(key);
         if (existing) {

package/dist/cli.mjs

@@ -13,6 +13,7 @@
  *   latest-feedback <repoRoot> <taskId>
  *   emit-gate-decision <repoRoot> <workItemId> <gate> <decision> <actor> [--comment=<str>]
  *   ui-review-config --repo-root <repoRoot>
+ *   plugin-root
  */
 import { readFileSync } from 'node:fs';
 import { execSync } from 'node:child_process';
@@ -26,6 +27,7 @@ import { loadUiPathsConfig } from './ui-paths.mjs';
 import { computeAffectedRoutes } from './affected-routes.mjs';
 import { loadAffectedRoutesConfig } from './affected-routes.mjs';
 import { loadUiReviewConfig } from './ui-review-config.mjs';
+import { getPluginRoot } from './plugin-path.mjs';
 function die(msg, code = 1) {
     process.stderr.write(msg + '\n');
     process.exit(code);
@@ -42,7 +44,8 @@ function usage(msg) {
         '  write-feedback <repoRoot> <taskId> <envelopeJsonPath>\n' +
         '  latest-feedback <repoRoot> <taskId>\n' +
         '  emit-gate-decision <repoRoot> <workItemId> <gate> <decision> <actor> [--comment=<str>]\n' +
-        '  ui-review-config --repo-root <repoRoot>\n');
+        '  ui-review-config --repo-root <repoRoot>\n' +
+        '  plugin-root\n');
     process.exit(2);
 }
 const [, , command, ...rest] = process.argv;
@@ -235,6 +238,10 @@ try {
             process.stdout.write(JSON.stringify(config, null, 2));
             process.exit(0);
         }
+        case 'plugin-root': {
+            process.stdout.write(getPluginRoot());
+            process.exit(0);
+        }
         default:
             usage(`Unknown command: ${command}`);
     }

package/dist/feedback.mjs

@@ -29,7 +29,7 @@ export function allFeedback(repoRoot, taskId) {
     const dir = feedbackDir(repoRoot);
     if (!existsSync(dir))
         return [];
-    const re = new RegExp(`^${escapeRegex(taskId)}-r(\\d+)\\.json$`);
+    const re = new RegExp(`^${escapeRegex(taskId)}-[ruq](\\d+)\\.json$`);
     const entries = readdirSync(dir)
         .map((f) => ({ f, m: f.match(re) }))
         .filter((x) => !!x.m)

package/dist/plugin-path.mjs

@@ -0,0 +1,19 @@
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+const here = dirname(fileURLToPath(import.meta.url));
+/**
+ * Absolute path to the plugin root.
+ *
+ * At runtime, this module lives at <plugin-root>/lib/plugin-path.js (or .ts in dev),
+ * so the plugin root is the parent directory.
+ *
+ * Works under:
+ * - dev mode (repo source: <repo>/reference-impl/)
+ * - npm install (node_modules/@cloverleaf/reference-impl/)
+ * - claude plugin install cache (~/.claude/plugins/cache/cloverleaf-local/cloverleaf/0.4.1/)
+ * - legacy symlink into ~/.claude/plugins/cloverleaf/
+ * - claude --plugin-dir <path>
+ */
+export function getPluginRoot() {
+    return resolve(here, '..');
+}

package/dist/ui-review-config.mjs

@@ -10,11 +10,15 @@ const HARDCODED_FALLBACK = {
         desktop: { width: 1280, height: 800 },
     },
     visualDiff: { enabled: true, threshold: 0.1, maxDiffRatio: 0.01, mask: [] },
-    axe: { viewports: ['desktop'], dedupeBy: ['ruleId', 'target'] },
+    axe: { viewports: ['desktop'], dedupeBy: ['ruleId', 'target'], ignored: [] },
 };
 function readAsConfig(path) {
     try {
         const doc = JSON.parse(readFileSync(path, 'utf-8'));
+        // Back-compat: if ignored is missing from an older override, default it.
+        if (doc.axe && !('ignored' in doc.axe)) {
+            doc.axe.ignored = [];
+        }
         return doc;
     }
     catch {

package/lib/axe-dedupe.ts

@@ -24,9 +24,20 @@ function dedupeKeyOf(raw: RawAxeFinding, keys: DedupeKey[]): string {
   return keys.map((k) => raw[k]).join('||');
 }
 
-export function dedupeAxeFindings(raws: RawAxeFinding[], keys: DedupeKey[]): Finding[] {
+export function dedupeAxeFindings(
+  raws: RawAxeFinding[],
+  keys: DedupeKey[],
+  ignored: Array<{ ruleId: string; target: string }> = []
+): Finding[] {
+  // Filter out ignored (ruleId, target) tuples BEFORE grouping.
+  const filtered = raws.filter((raw) => {
+    return !ignored.some(
+      (i) => i.ruleId === raw.ruleId && i.target === raw.target
+    );
+  });
+
   const groups = new Map<string, { first: RawAxeFinding; viewports: string[] }>();
-  for (const raw of raws) {
+  for (const raw of filtered) {
     const key = dedupeKeyOf(raw, keys);
     const existing = groups.get(key);
     if (existing) {

package/lib/cli.ts

@@ -13,6 +13,7 @@
  *   latest-feedback <repoRoot> <taskId>
  *   emit-gate-decision <repoRoot> <workItemId> <gate> <decision> <actor> [--comment=<str>]
  *   ui-review-config --repo-root <repoRoot>
+ *   plugin-root
  */
 
 import { readFileSync } from 'node:fs';
@@ -27,6 +28,7 @@ import { loadUiPathsConfig } from './ui-paths.js';
 import { computeAffectedRoutes } from './affected-routes.js';
 import { loadAffectedRoutesConfig } from './affected-routes.js';
 import { loadUiReviewConfig } from './ui-review-config.js';
+import { getPluginRoot } from './plugin-path.js';
 import type { FeedbackEnvelope } from './feedback.js';
 
 function die(msg: string, code = 1): never {
@@ -46,7 +48,8 @@ function usage(msg?: string): never {
       '  write-feedback <repoRoot> <taskId> <envelopeJsonPath>\n' +
       '  latest-feedback <repoRoot> <taskId>\n' +
       '  emit-gate-decision <repoRoot> <workItemId> <gate> <decision> <actor> [--comment=<str>]\n' +
-      '  ui-review-config --repo-root <repoRoot>\n'
+      '  ui-review-config --repo-root <repoRoot>\n' +
+      '  plugin-root\n'
   );
   process.exit(2);
 }
@@ -244,6 +247,11 @@ try {
       process.exit(0);
     }
 
+    case 'plugin-root': {
+      process.stdout.write(getPluginRoot());
+      process.exit(0);
+    }
+
     default:
       usage(`Unknown command: ${command}`);
   }

package/lib/feedback.ts

@@ -70,7 +70,7 @@ export function latestFeedback(repoRoot: string, taskId: string): FeedbackEnvelo
 export function allFeedback(repoRoot: string, taskId: string): FeedbackEnvelope[] {
   const dir = feedbackDir(repoRoot);
   if (!existsSync(dir)) return [];
-  const re = new RegExp(`^${escapeRegex(taskId)}-r(\\d+)\\.json$`);
+  const re = new RegExp(`^${escapeRegex(taskId)}-[ruq](\\d+)\\.json$`);
   const entries = readdirSync(dir)
     .map((f) => ({ f, m: f.match(re) }))
     .filter((x): x is { f: string; m: RegExpMatchArray } => !!x.m)

package/lib/plugin-path.ts

@@ -0,0 +1,21 @@
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Absolute path to the plugin root.
+ *
+ * At runtime, this module lives at <plugin-root>/lib/plugin-path.js (or .ts in dev),
+ * so the plugin root is the parent directory.
+ *
+ * Works under:
+ * - dev mode (repo source: <repo>/reference-impl/)
+ * - npm install (node_modules/@cloverleaf/reference-impl/)
+ * - claude plugin install cache (~/.claude/plugins/cache/cloverleaf-local/cloverleaf/0.4.1/)
+ * - legacy symlink into ~/.claude/plugins/cloverleaf/
+ * - claude --plugin-dir <path>
+ */
+export function getPluginRoot(): string {
+  return resolve(here, '..');
+}

package/lib/ui-review-config.ts

@@ -21,6 +21,7 @@ export interface UiReviewConfig {
   axe: {
     viewports: string[];
     dedupeBy: ('ruleId' | 'target')[];
+    ignored: Array<{ ruleId: string; target: string }>;
   };
 }
 
@@ -31,12 +32,16 @@ const HARDCODED_FALLBACK: UiReviewConfig = {
     desktop: { width: 1280, height: 800  },
   },
   visualDiff: { enabled: true, threshold: 0.1, maxDiffRatio: 0.01, mask: [] },
-  axe: { viewports: ['desktop'], dedupeBy: ['ruleId', 'target'] },
+  axe: { viewports: ['desktop'], dedupeBy: ['ruleId', 'target'], ignored: [] },
 };
 
 function readAsConfig(path: string): UiReviewConfig | null {
   try {
     const doc = JSON.parse(readFileSync(path, 'utf-8')) as UiReviewConfig;
+    // Back-compat: if ignored is missing from an older override, default it.
+    if (doc.axe && !('ignored' in doc.axe)) {
+      (doc.axe as UiReviewConfig['axe']).ignored = [];
+    }
     return doc;
   } catch {
     return null;

package/package.json

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

@@ -13,9 +13,21 @@ You are the Cloverleaf UI Reviewer. Your job: review a task's UI changes at mult
 - **Affected routes**: {{affected_routes}} — either a JSON array of route paths (e.g., `["/faq/"]`), or the string `"all"`, or `[]`
 - **UI review config**: {{ui_review_config}} — the loaded `UiReviewConfig` object (viewports, visualDiff, axe) as JSON. The `viewports` array contains named entries such as `mobile`, `tablet`, and `desktop` with their respective `{ width, height }` dimensions.
 
+## Paths
+
+You operate in two filesystem locations — keep them straight:
+
+- `<worktree>` — the ephemeral worktree at `$TMPDIR` (set up in step 2 of the Runtime procedure). You run the dev server here and execute Playwright here.
+- `<repoRoot>` — the main repository root at `{{repo_root}}` (always an absolute path). This is the ONLY location where baselines, diff PNGs, candidate PNGs, and artifacts are written.
+
+**All `compareVisual` paths MUST be rooted at `{{repo_root}}`, NOT at `$TMPDIR`.**
+
+The rationale: baselines on `{{repo_root}}/.cloverleaf/baselines/` get picked up by subsequent `git add` + `git commit` steps in the UI Reviewer, which run on the feature branch. The merge skill (v0.4.1+) then merges those commits to main via `git merge --no-ff`. Writing to the worktree's `.cloverleaf/` would strand the files and `git worktree remove --force` would discard them on teardown.
+
 ## Scope (v0.4)
 
 - **Accessibility (axe-core):** run at the viewports listed in `{{ui_review_config}}.axe.viewports`.
+  Apply the allowlist in `{{ui_review_config}}.axe.ignored` to drop pre-existing violations that the consumer has accepted (e.g., a11y debt being tracked separately).
   Dedupe findings across viewports by the `{{ui_review_config}}.axe.dedupeBy` composite key (default `["ruleId", "target"]`).
   Emit one finding per (ruleId, target) pair, with a `metadata.viewports` array aggregating the viewports where the violation was detected.
 - **Visual diff (pixelmatch):** when `{{ui_review_config}}.visualDiff.enabled` is true, screenshot each route at each viewport in `{{ui_review_config}}.viewports`, compare to `.cloverleaf/baselines/{route-slug}-{viewport}.png`, emit `severity: "info"` findings with baseline/candidate/diff attachments when the diff ratio exceeds `maxDiffRatio`.
@@ -50,7 +62,7 @@ The `PLAYWRIGHT_BROWSERS_PATH` environment variable is set to `~/.cache/ms-playw
 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:
-   1. Check `<repoRoot>/.cloverleaf/config/astro-base.json`. Expected shape: `{ "base": "<path>" }`. If present, use the `base` field verbatim and skip to step 6. (Consumer override — checked before parsing astro config.)
+   1. Check `{{repo_root}}/.cloverleaf/config/astro-base.json`. Expected shape: `{ "base": "<path>" }`. If present, use the `base` field verbatim and skip to step 6. (Consumer override — checked before parsing astro config.)
    2. Otherwise, attempt to locate and parse an astro config file (common locations: `site/astro.config.mjs`, `astro.config.mjs` at repo root, `apps/web/astro.config.mjs`). Best-effort fallback.
    3. If both fail, treat base as empty string.
 
@@ -61,11 +73,12 @@ The `PLAYWRIGHT_BROWSERS_PATH` environment variable is set to `~/.cache/ms-playw
    - Navigate to `http://localhost:{{preview_port}}<base><route>`. If 404, retry without the base.
    - `page.screenshot({ fullPage: false })` → candidate PNG buffer.
    - Compute slug for the route (lowercase, strip leading/trailing slashes, replace slashes with hyphens; `/` → `index`).
+   - Note: use `{{repo_root}}` (the absolute main-repo path), NOT `$TMPDIR` or the worktree. See the "Paths" section.
    - Call `compareVisual` (from `lib/visual-diff.ts`) with:
-     - `baselinePath = <repoRoot>/.cloverleaf/baselines/{slug}-{viewport}.png`
+     - `baselinePath = {{repo_root}}/.cloverleaf/baselines/{slug}-{viewport}.png`
      - `candidateBuf = <candidate PNG>`
-     - `diffPath = <repoRoot>/.cloverleaf/runs/{taskId}/ui-review/diff-{slug}-{viewport}.png`
-     - `candidateOutPath = <repoRoot>/.cloverleaf/runs/{taskId}/ui-review/candidate-{slug}-{viewport}.png`
+     - `diffPath = {{repo_root}}/.cloverleaf/runs/{taskId}/ui-review/diff-{slug}-{viewport}.png`
+     - `candidateOutPath = {{repo_root}}/.cloverleaf/runs/{taskId}/ui-review/candidate-{slug}-{viewport}.png`
      - `threshold = visualDiff.threshold`
      - `maxDiffRatio = visualDiff.maxDiffRatio`
    - Map result to a finding:
@@ -86,7 +99,7 @@ The `PLAYWRIGHT_BROWSERS_PATH` environment variable is set to `~/.cache/ms-playw
        ```
      - Collect each violation as a raw tuple: `{ viewport, ruleId, target, impact, message, helpUrl }` (from `axe.run` output).
 
-8. Dedupe raw axe findings via `dedupeAxeFindings(raws, {{ui_review_config}}.axe.dedupeBy)` (from `lib/axe-dedupe.ts`). Emit the returned `Finding[]`.
+8. Dedupe raw axe findings via `dedupeAxeFindings(raws, {{ui_review_config}}.axe.dedupeBy, {{ui_review_config}}.axe.ignored)` (from `lib/axe-dedupe.ts`). The `ignored` parameter drops any finding whose `(ruleId, target)` exactly matches an allowlist entry BEFORE dedupe/grouping. Emit the returned `Finding[]`.
 
 9. Severity mapping (preserved from v0.3 via `dedupeAxeFindings`):
    - axe `impact: "critical"` → `severity: "blocker"`
@@ -109,7 +122,7 @@ The `PLAYWRIGHT_BROWSERS_PATH` environment variable is set to `~/.cache/ms-playw
 ## Tool constraints
 
 - Read-only for source files and tests.
-- You MAY write under `<repoRoot>/.cloverleaf/baselines/` and `<repoRoot>/.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 and artifacts.
 - Use `git worktree`: do NOT `git checkout` in the main working directory.
 - Always teardown the server and worktree, even on error.
 

package/skills/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/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/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/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`).
 

package/skills/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.
 
@@ -30,7 +34,7 @@ description: Run the QA agent on a task in the `qa` state (full pipeline only).
    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`.
@@ -43,7 +47,7 @@ description: Run the QA agent on a task in the `qa` state (full pipeline only).
 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 5).
+   - 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).
 
 8. Parse response: expect `{"verdict": "pass"|"bounce"|"escalate", "summary", "findings", "results"}`.
 
@@ -59,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/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/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,11 +17,15 @@ 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.
 
@@ -35,7 +39,7 @@ description: Run the UI Reviewer agent on a task in the `ui-review` state (full
 
 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>)
    ```
 
 6. **Empty-set early-exit.** If `AFFECTED` is `[]`, skip the subagent entirely:
@@ -63,7 +67,7 @@ description: Run the UI Reviewer agent on a task in the `ui-review` state (full
 10. 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:
+    - 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)
@@ -82,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`