@cloverleaf/reference-impl 0.4.0 → 0.5.0

package/skills/cloverleaf-gate/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: cloverleaf-gate
+description: Human gate action on an RFC (rfc_strategy_gate) or Plan (task_batch_gate) in status gate-pending. Usage — /cloverleaf-gate <item-id> <approve|reject|revise> [reason]. `revise` is valid only at rfc_strategy_gate (RFC only).
+---
+
+# Cloverleaf — human gate
+
+The user has invoked this skill with `<item-id> <action> [reason]`.
+
+## Steps
+
+1. Capture arguments:
+   - `$ITEM_ID` = first positional arg
+   - `$ACTION` = second positional arg (must be `approve`, `reject`, or `revise`)
+   - `$REASON` = remaining args joined with spaces (optional)
+
+   If `ITEM_ID` or `ACTION` is missing, report usage and stop.
+
+2. Validate action:
+   ```bash
+   case "$ACTION" in
+     approve|reject|revise) ;;
+     *) echo "Invalid action: $ACTION. Use approve, reject, or revise." >&2; exit 1 ;;
+   esac
+   ```
+
+3. Detect work-item type by checking which directory has the JSON file:
+   ```bash
+   if [ -f "<repo_root>/.cloverleaf/rfcs/$ITEM_ID.json" ]; then
+     TYPE=rfc
+     GATE=rfc_strategy_gate
+   elif [ -f "<repo_root>/.cloverleaf/plans/$ITEM_ID.json" ]; then
+     TYPE=plan
+     GATE=task_batch_gate
+   else
+     echo "No RFC or Plan found with ID $ITEM_ID" >&2
+     exit 1
+   fi
+   ```
+
+4. Validate that `revise` is only valid at `rfc_strategy_gate` (i.e., on RFCs — revise is only exclusive to rfc_strategy_gate):
+   ```bash
+   if [ "$ACTION" = "revise" ] && [ "$TYPE" != "rfc" ]; then
+     echo "revise is only valid at rfc_strategy_gate (RFCs). Use reject on Plans." >&2
+     exit 2
+   fi
+   ```
+
+5. Verify the item is in `gate-pending` status:
+   ```bash
+   STATUS=$(cloverleaf-cli load-$TYPE <repo_root> $ITEM_ID | jq -r .status)
+   if [ "$STATUS" != "gate-pending" ]; then
+     echo "$TYPE $ITEM_ID is in status '$STATUS', not gate-pending" >&2
+     exit 3
+   fi
+   ```
+
+6. Emit the gate-decision event:
+   ```bash
+   if [ -n "$REASON" ]; then
+     cloverleaf-cli emit-gate-decision <repo_root> $ITEM_ID $GATE $ACTION human --comment="$REASON"
+   else
+     cloverleaf-cli emit-gate-decision <repo_root> $ITEM_ID $GATE $ACTION human
+   fi
+   ```
+
+7. Advance the work-item state:
+   ```bash
+   case "$ACTION" in
+     approve)
+       cloverleaf-cli advance-$TYPE <repo_root> $ITEM_ID approved human $GATE
+       ;;
+     reject)
+       cloverleaf-cli advance-$TYPE <repo_root> $ITEM_ID rejected human $GATE
+       ;;
+     revise)
+       # RFC-only — validated in step 4
+       cloverleaf-cli advance-rfc <repo_root> $ITEM_ID drafting human $GATE
+       # Persisting the revise reason as a feedback finding is deferred to v0.6.
+       # For now, the reason is surfaced on stdout so the caller can capture it
+       # and pass it back via the next /cloverleaf-draft-rfc invocation context.
+       if [ -n "$REASON" ]; then
+         echo "revise reason: $REASON"
+       fi
+       ;;
+   esac
+   ```
+
+8. Commit state files:
+   ```bash
+   git add .cloverleaf/rfcs/ .cloverleaf/plans/ .cloverleaf/events/
+   git commit -m "cloverleaf: gate $ITEM_ID $ACTION ($GATE)"
+   ```
+
+9. Print the new status:
+   ```bash
+   NEW=$(cloverleaf-cli load-$TYPE <repo_root> $ITEM_ID | jq -r .status)
+   echo "$ITEM_ID: $STATUS → $NEW"
+   ```
+
+## Notes
+
+- `revise` (RFC only) returns the RFC to `drafting`. The orchestrator loops back to `/cloverleaf-draft-rfc`.
+- On `reject` of an RFC: terminal (enters rejected state; orchestrator halts).
+- On `reject` of a Plan: plan enters rejected state; it can be re-decomposed via a new `/cloverleaf-breakdown` run (rejected → drafting via agent is a legal transition).
+- `[reason]` text is persisted in the gate_decision event's `comment` field. For `revise`, it's also echoed to stdout so the calling orchestrator can feed it back to the Researcher on re-draft.

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-rfc/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: cloverleaf-new-rfc
+description: Scaffold a new RFC work item from a brief file. Usage — /cloverleaf-new-rfc <brief-file>. Writes `.cloverleaf/rfcs/<ID>.json` with status=drafting and empty body fields (populated by /cloverleaf-draft-rfc). Returns the new RFC ID.
+---
+
+# Cloverleaf — new RFC
+
+## Steps
+
+1. Capture `<brief-file>` (first positional arg). Verify file exists:
+
+```bash
+BRIEF_FILE="$1"
+[ -f "$BRIEF_FILE" ] || { echo "Brief file not found: $BRIEF_FILE" >&2; exit 1; }
+```
+
+2. Load the discovery config to get `projectId`:
+
+```bash
+CFG=$(cloverleaf-cli discovery-config --repo-root $(pwd))
+PROJECT_ID=$(echo "$CFG" | jq -r .projectId)
+[ -z "$PROJECT_ID" ] && { echo "set projectId in .cloverleaf/config/discovery.json" >&2; exit 2; }
+```
+
+3. Compute next work-item ID:
+
+```bash
+RFC_ID=$(cloverleaf-cli next-work-item-id $(pwd) "$PROJECT_ID")
+```
+
+4. Read brief content:
+
+```bash
+BRIEF_CONTENT=$(cat "$BRIEF_FILE")
+```
+
+5. Build the RFC skeleton JSON. Derive a short title from the brief's first non-empty line (truncate if long). Problem = brief content. All other body fields are seeded with schema-conformant placeholders that `/cloverleaf-draft-rfc` will overwrite.
+
+```bash
+FIRST_LINE=$(head -n 1 "$BRIEF_FILE" | sed 's/^# *//' | cut -c1-120)
+TMPFILE=$(mktemp --suffix=.json)
+
+cat > "$TMPFILE" <<EOF
+{
+  "type": "rfc",
+  "project": "$PROJECT_ID",
+  "id": "$RFC_ID",
+  "status": "drafting",
+  "owner": { "kind": "agent", "id": "researcher" },
+  "title": $(echo "$FIRST_LINE" | jq -Rs .),
+  "problem": $(echo "$BRIEF_CONTENT" | jq -Rs .),
+  "solution": "TBD — to be populated by /cloverleaf-draft-rfc.",
+  "unknowns": [],
+  "acceptance_criteria": ["RFC body populated by researcher agent"],
+  "out_of_scope": []
+}
+EOF
+```
+
+6. Save via CLI (validates against rfc.schema.json):
+
+```bash
+cloverleaf-cli save-rfc $(pwd) "$TMPFILE"
+rm "$TMPFILE"
+```
+
+7. Print the new RFC ID to stdout:
+
+```bash
+echo "$RFC_ID"
+```
+
+## Notes
+
+- This skill does NOT invoke the Researcher agent. Use `/cloverleaf-draft-rfc <RFC_ID>` to populate body from the brief + doc grounding.
+- To drive the whole Discovery flow end-to-end, use `/cloverleaf-discover <brief-file>` instead.

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-spike/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: cloverleaf-spike
+description: Run a single Spike via the Researcher agent (operation=runSpike). Advances pending → running → completed with findings + recommendation. Usage — /cloverleaf-spike <SPIKE-ID>.
+---
+
+# Cloverleaf — run Spike
+
+The user has invoked this skill with a SPIKE-ID (e.g., `CLV-010`).
+
+## Steps
+
+1. Capture `<SPIKE-ID>` as `$SPIKE_ID`. If missing, report usage and stop.
+
+2. Load the spike:
+   ```
+   cloverleaf-cli load-spike <repo_root> <SPIKE-ID>
+   ```
+   Verify `status === "pending"`. If not, report and stop.
+
+3. Transition pending → running:
+   ```
+   cloverleaf-cli advance-spike <repo_root> <SPIKE-ID> running agent
+   ```
+
+4. Load discovery config:
+   ```bash
+   DOC_CTX=$(cloverleaf-cli discovery-config --repo-root <repo_root> | jq -r .docContextUri)
+   ```
+
+5. Dispatch the Researcher subagent via the Task tool:
+   - `subagent_type`: `general-purpose`
+   - `model`: `sonnet`
+   - Prompt: contents of `$(cloverleaf-cli plugin-root)/prompts/researcher.md`, with placeholders:
+     - `{{operation}}` → `runSpike`
+     - `{{spike}}` → the full spike JSON (from step 2, with status now `running`)
+     - `{{doc_context_uri}}` → `$DOC_CTX`
+     - `{{repo_root}}` → absolute path to the current repo
+     - `{{brief}}` → `null` (unused for runSpike)
+     - `{{prior_rfc}}`, `{{completed_spikes}}` → `null`
+
+6. Parse subagent response. Expected: the spike JSON with `status: "completed"`, `findings: string`, `recommendation: string`. Schema: `spike.schema.json` (validated by save-spike).
+
+   If output fails schema validation: bounce. Budget: 3 bounces. On exhaustion: report and stop without advancing to completed.
+
+7. Save the completed spike:
+   ```
+   cloverleaf-cli save-spike <repo_root> /tmp/spike-$SPIKE_ID.json
+   ```
+
+8. Transition running → completed:
+   ```
+   cloverleaf-cli advance-spike <repo_root> <SPIKE-ID> completed agent
+   ```
+
+9. Commit:
+   ```bash
+   git add .cloverleaf/spikes/ .cloverleaf/events/
+   git commit -m "cloverleaf: spike $SPIKE_ID completed"
+   ```
+
+10. Report: spike findings summary.
+
+## Notes
+
+- Orchestrator (`/cloverleaf-discover`) loops this for every spike in the RFC's `unknowns[]` (materialised as Spike work items by `/cloverleaf-draft-rfc`) before re-drafting the RFC.
+- If `method === "prototype"` or `method === "benchmark"`: the Researcher agent describes what to prototype/benchmark, not implement it. v0.5 does not build prototypes — that's Delivery's job.

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`

package/lib/state.ts

@@ -1,137 +0,0 @@
-import { readFileSync, writeFileSync, existsSync } from 'node:fs';
-import { join } from 'node:path';
-import { createRequire } from 'node:module';
-import { randomUUID } from 'node:crypto';
-import { tasksDir, projectsDir } from './paths.js';
-import { emitStatusTransition, formatReason } from './events.js';
-
-// Import validator from @cloverleaf/standard.
-// The standard package ships TypeScript source only with no exports map.
-// Vitest (via vite-node) resolves .js → .ts for workspace symlinked packages,
-// so the .js convention works here. If it ever fails with "module not found",
-// switch the specifier to '@cloverleaf/standard/validators/index.ts'.
-import { validateStatusTransitionLegality } from '@cloverleaf/standard/validators/index.js';
-import type { StatusTransitions, Task as SMTask } from '@cloverleaf/standard/validators/index.js';
-import { validateOrThrow } from './validate.js';
-
-const req = createRequire(import.meta.url);
-
-export interface TaskDoc {
-  type: 'task';
-  project: string;
-  id: string;
-  title: string;
-  status: string;
-  risk_class: 'low' | 'high';
-  owner: { kind: 'agent' | 'human' | 'system'; id: string };
-  acceptance_criteria: string[];
-  definition_of_done: string[];
-  context: Record<string, unknown>;
-  [key: string]: unknown;
-}
-
-export interface ProjectDoc {
-  key: string;
-  name: string;
-  [key: string]: unknown;
-}
-
-export function loadTask(repoRoot: string, taskId: string): TaskDoc {
-  const path = join(tasksDir(repoRoot), `${taskId}.json`);
-  if (!existsSync(path)) throw new Error(`Task ${taskId} not found at ${path}`);
-  return JSON.parse(readFileSync(path, 'utf-8')) as TaskDoc;
-}
-
-export function saveTask(repoRoot: string, task: TaskDoc): void {
-  validateOrThrow('https://cloverleaf.example/schemas/task.schema.json', task);
-  const path = join(tasksDir(repoRoot), `${task.id}.json`);
-  writeFileSync(path, JSON.stringify(task, null, 2) + '\n');
-}
-
-export function loadProject(repoRoot: string, projectId: string): ProjectDoc {
-  const path = join(projectsDir(repoRoot), `${projectId}.json`);
-  if (!existsSync(path)) throw new Error(`Project ${projectId} not found at ${path}`);
-  return JSON.parse(readFileSync(path, 'utf-8')) as ProjectDoc;
-}
-
-function loadTaskStateMachine(): StatusTransitions {
-  // state-machines/task.json is a static JSON asset. Navigate from standard's
-  // package.json — no exports map support needed.
-  const pkgPath = req.resolve('@cloverleaf/standard/package.json');
-  const pkgDir = pkgPath.replace(/\/package\.json$/, '');
-  return JSON.parse(readFileSync(`${pkgDir}/state-machines/task.json`, 'utf-8')) as StatusTransitions;
-}
-
-export function advanceStatus(
-  repoRoot: string,
-  taskId: string,
-  toStatus: string,
-  actor: 'agent' | 'human',
-  options: { gate?: string; path?: 'fast_lane' | 'full_pipeline' } = {}
-): TaskDoc {
-  const task = loadTask(repoRoot, taskId);
-  const from = task.status;
-  const sm = loadTaskStateMachine();
-
-  // Read risk_class directly from the task (defaulting to 'low' if absent).
-  // The validator derives itemPath from workItem.risk_class: low → fast_lane, else full_pipeline.
-  // If caller passed options.path, translate it back to risk_class for the validator.
-  const riskClass: 'low' | 'high' =
-    options.path === 'fast_lane' ? 'low'
-    : options.path === 'full_pipeline' ? 'high'
-    : (task.risk_class ?? 'low');
-
-  // Build a minimal Task-shaped object so the validator can resolve path-tagged transitions.
-  const workItemForValidator: SMTask = {
-    type: 'task',
-    id: task.id,
-    project: task.project,
-    status: task.status,
-    risk_class: riskClass,
-    context: { rfc: { project: task.project, id: task.id } },
-    definition_of_done: task.definition_of_done,
-    acceptance_criteria: task.acceptance_criteria,
-  };
-
-  const reason = formatReason({ gate: options.gate, path: options.path });
-  const event = {
-    event_id: randomUUID(),
-    event_type: 'status_transition' as const,
-    occurred_at: new Date().toISOString(),
-    work_item_id: { project: task.project, id: task.id },
-    work_item_type: 'task' as const,
-    from_status: from,
-    to_status: toStatus,
-    actor: { kind: actor, id: actor },
-    ...(reason ? { reason } : {}),
-  };
-
-  const result = validateStatusTransitionLegality(event, sm, workItemForValidator);
-  if (!result.ok) {
-    const msgs = result.violations.map((v) => v.message).join('; ');
-    throw new Error(`Illegal transition ${from} → ${toStatus}: ${msgs}`);
-  }
-
-  // NEW: emit first, save second. validateStatusTransitionLegality stays above.
-  const emittedPath = emitStatusTransition(repoRoot, {
-    project: task.project,
-    workItemType: 'task',
-    workItemId: task.id,
-    from,
-    to: toStatus,
-    actor,
-    gate: options.gate,
-    path: options.path,
-  });
-
-  const proposed = { ...task, status: toStatus };
-  try {
-    saveTask(repoRoot, proposed);
-  } catch (err) {
-    const inner = err instanceof Error ? err.message : String(err);
-    throw new Error(
-      `orphan event written to ${emittedPath} but task save failed: ${inner}`
-    );
-  }
-  return proposed;
-}