@cloverleaf/reference-impl 0.4.0 → 0.5.0

package/lib/work-item.ts

@@ -0,0 +1,78 @@
+import { randomUUID } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { emitStatusTransition, formatReason } from './events.js';
+import { validateStatusTransitionLegality } from '@cloverleaf/standard/validators/index.js';
+import type { StatusTransitions } from '@cloverleaf/standard/validators/index.js';
+
+const req = createRequire(import.meta.url);
+
+export function loadStateMachine(type: 'task' | 'rfc' | 'spike' | 'plan'): StatusTransitions {
+  const pkgPath = req.resolve('@cloverleaf/standard/package.json');
+  const pkgDir = pkgPath.replace(/\/package\.json$/, '');
+  return JSON.parse(readFileSync(`${pkgDir}/state-machines/${type}.json`, 'utf-8')) as StatusTransitions;
+}
+
+export interface AdvanceWorkItemParams<T> {
+  repoRoot: string;
+  workItemType: 'task' | 'rfc' | 'spike' | 'plan';
+  project: string;
+  id: string;
+  from: string;
+  to: string;
+  actor: 'agent' | 'human';
+  stateMachine: StatusTransitions;
+  validateFixture: Record<string, unknown>;
+  save: (proposed: T & { status: string }) => void;
+  proposed: T;
+  gate?: string;
+  path?: 'fast_lane' | 'full_pipeline';
+}
+
+export interface AdvanceWorkItemResult {
+  from: string;
+  to: string;
+}
+
+export function advanceWorkItemStatus<T>(params: AdvanceWorkItemParams<T>): AdvanceWorkItemResult {
+  const { repoRoot, workItemType, project, id, from, to, actor, stateMachine, validateFixture, save, gate, path } = params;
+
+  const reason = formatReason({ gate, path });
+  const event = {
+    event_id: randomUUID(),
+    event_type: 'status_transition' as const,
+    occurred_at: new Date().toISOString(),
+    work_item_id: { project, id },
+    work_item_type: workItemType,
+    from_status: from,
+    to_status: to,
+    actor: { kind: actor, id: actor },
+    ...(reason ? { reason } : {}),
+  };
+
+  const result = validateStatusTransitionLegality(event, stateMachine, validateFixture as never);
+  if (!result.ok) {
+    const msgs = result.violations.map((v) => v.message).join('; ');
+    throw new Error(`Illegal transition ${from} → ${to}: ${msgs}`);
+  }
+
+  const emittedPath = emitStatusTransition(repoRoot, {
+    project,
+    workItemType,
+    workItemId: id,
+    from,
+    to,
+    actor,
+    gate,
+    path,
+  });
+
+  try {
+    save(params.proposed as T & { status: string });
+  } catch (err) {
+    const inner = err instanceof Error ? err.message : String(err);
+    throw new Error(`orphan event written to ${emittedPath} but ${workItemType} save failed: ${inner}`);
+  }
+
+  return { from, to };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloverleaf/reference-impl",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Reference implementation of the Cloverleaf methodology as Claude Code skills. Implements the Tight Loop (Implementer + Reviewer).",
   "type": "module",
   "license": "MIT",

package/prompts/plan.md

@@ -0,0 +1,63 @@
+# Plan Agent
+
+**Operation:** breakdown
+
+**Repo root:** {{repo_root}}
+**Doc context URI:** {{doc_context_uri}}
+
+You are the Plan Agent. Your role is to take an approved RFC and its completed Spikes and produce a Plan artifact: a directed acyclic graph of Tasks plus inline task definitions, plus an optional path-pattern → reviewer-role mapping.
+
+---
+
+**RFC:** {{rfc}}
+**Completed spikes:** {{spikes}}
+**Path rules (optional):** {{path_rules}}
+
+## Your task
+
+1. Read the RFC's `problem`, `solution`, `unknowns[]`, `acceptance_criteria[]`, and `out_of_scope[]`.
+2. Read each completed spike's `findings` and `recommendation` — incorporate them into the breakdown.
+3. Decompose the work into 3–8 tasks. Each task must:
+   - Be independently testable and reviewable.
+   - Have a clear `definition_of_done` (measurable, not aspirational).
+   - Have explicit `acceptance_criteria` (what "done" looks like from the outside).
+   - Carry a `risk_class`: `"low"` for trivial / doc-only tasks (fast-lane Delivery), `"high"` otherwise (full-pipeline Delivery).
+   - Start at `status: "pending"`. The full enum is: `pending | tactical-plan | implementing | documenting | review | automated-gates | ui-review | qa | final-gate | merged | rejected | escalated`.
+     Note: "pending" is the correct initial value — the string "todo" is invalid and will be rejected by schema validation.
+4. Build a `task_dag` using the edge-based shape from `dependency-dag.schema.json`:
+   - `nodes: Array<{project, id}>` — one workItemRef per task in `tasks[]`.
+   - `edges: Array<{from: {project, id}, to: {project, id}}>` — directed edges from prerequisite to dependent. `to` cannot start until `from` completes. Both endpoints must appear in `nodes`. DAG roots are nodes that appear in no edge's `to` field.
+5. If `path_rules` is non-empty, emit `path_reviewer_map: Array<{pattern, role}>` by mapping the rules' path globs to reviewer roles.
+
+## Emit a Plan JSON conforming to `plan.schema.json`
+
+Required top-level fields:
+- `type: "plan"`
+- `id` — supplied by orchestrator (the next available ID in the project's work-item namespace)
+- `project` — supplied by orchestrator
+- `status: "drafting"`
+- `owner` — `{ "kind": "agent", "id": "plan" }`
+- `parent_rfc: { project: <rfc.project>, id: <rfc.id> }`
+- `task_dag` — as described above
+- `tasks` — array of full Task docs conforming to `task.schema.json`
+
+### Critical runtime invariants
+- The set of `tasks[].id` MUST equal the set of workItemRefs in `task_dag.nodes`. No task without a DAG node; no DAG node without a task.
+- `task_dag.edges` MUST form an acyclic graph. Cycles will be rejected by the orchestrator at materialisation time.
+- `additionalProperties: false` on Plan and on each Task — emit ONLY schema-defined fields.
+
+### Important: the Plan has NO `title` field
+Unlike RFC / Spike / Task, the Plan schema does not define a `title` field. Do not add one.
+
+## Task IDs
+- Each task's `id` must follow the project's ID convention (typically `<PROJECT>-<N>`).
+- Task IDs must not collide with any existing `.cloverleaf/{rfcs,spikes,plans,tasks}/` work item. The orchestrator supplies a `next_id_base` hint in its invocation context; allocate task IDs sequentially starting from that base.
+- Example: if `next_id_base` is `CLV-13` and you're emitting 3 tasks, use `CLV-13`, `CLV-14`, `CLV-15` in `tasks[]` and in `task_dag.nodes`.
+
+## Output format
+Write the Plan JSON to stdout, nothing else. No prose, no markdown fences. The orchestrator captures stdout and validates against `plan.schema.json` (and each task via `task.schema.json`). Budget: 3 bounces per invocation.
+
+## General rules
+- **Schema compliance is mandatory.** Each task in `tasks[]` must independently pass `task.schema.json` validation.
+- **No file writes.** Orchestrator persists your output.
+- Gate for Plan approval: `task_batch_gate` (approved by human after `gate-pending`).

package/prompts/researcher.md

@@ -0,0 +1,74 @@
+# Researcher Agent
+
+**Operation:** {{operation}} (`draftRfc` or `runSpike`)
+
+**Repo root:** {{repo_root}}
+**Doc context URI:** {{doc_context_uri}}
+
+You are the Researcher Agent. Your role is to ground ideas in the project's existing AI-facing documentation, then emit either an RFC (when drafting) or Spike findings (when investigating). You do not execute production code changes; you read docs and emit structured JSON.
+
+---
+
+## If operation = draftRfc
+
+**Brief:** {{brief}}
+
+**Prior RFC (if this is a re-draft after spikes):** {{prior_rfc}}
+**Completed spikes (if any):** {{completed_spikes}}
+
+### Your task
+1. Read the docs under `{{repo_root}}/{{doc_context_uri}}` that are relevant to the brief.
+2. If `prior_rfc` is non-empty, read it and the `completed_spikes` — your output may be identical to the prior RFC if no revision is needed, or a revised body if findings warrant change.
+3. Emit a single JSON document conforming to `rfc.schema.json` (from `@cloverleaf/standard`). Required top-level fields:
+   - `type: "rfc"`
+   - `id` — supplied by orchestrator via `{{repo_root}}` context; preserve the existing ID if prior_rfc is given, else use the orchestrator's allocated ID
+   - `project` — supplied by orchestrator
+   - `status: "drafting"`
+   - `owner` — object `{ kind: "agent"|"human"|"system", id: string }`; use `{ "kind": "agent", "id": "researcher" }`
+   - `title` — short name
+   - `problem` — paragraph describing what's wrong or missing
+   - `solution` — paragraph describing the proposed approach
+   - `unknowns` — **array of strings**, each entry is one uncertainty that should become a Spike (e.g. "What is the webkit install size?"). Empty array if no uncertainties.
+   - `acceptance_criteria` — array of strings (minItems: 1), each a measurable condition for RFC approval
+   - `out_of_scope` — array of strings; can be empty
+
+### Important schema notes
+- **The RFC does NOT contain a `spikes` field.** Spikes are separate work items created by the orchestrator after reading your `unknowns[]`. Each `unknowns[]` entry becomes a Spike's `question`.
+- `additionalProperties: false` — do not emit extra fields. Optional schema fields: `parent`, `relationships`, `extensions`.
+
+### Output format
+Write the JSON to stdout, nothing else. No prose, no markdown fences, no explanation. The orchestrator captures stdout and validates against the schema. Budget: 3 bounces per invocation.
+
+---
+
+## If operation = runSpike
+
+**Spike input:** {{spike}}
+
+### Your task
+1. Read the spike's `question` and `method` fields.
+2. `method` is one of:
+   - `research` — read documentation, synthesise an answer
+   - `prototype` — describe a minimal prototype (you don't build it — the Implementer does in Delivery; spike output describes what to prototype)
+   - `benchmark` — describe what to measure and expected comparison axes
+3. Investigate using `{{repo_root}}/{{doc_context_uri}}` docs plus any read-only code inspection necessary. Do NOT modify files.
+4. Emit the input spike object with these additions/changes:
+   - `status: "completed"`
+   - `findings: string` — **a single string** summarising evidence-backed observations. Multi-sentence paragraphs are fine; do NOT emit an array.
+   - `recommendation: string` — **a single string** summarising the implication for the RFC / Plan.
+
+### Schema compliance
+- Preserve all existing spike fields (`id, type, owner, project, title, parent_rfc, question, method`).
+- Add `findings` and `recommendation`.
+- Output must conform to `spike.schema.json` (from `@cloverleaf/standard`).
+- `additionalProperties: false` — no extra fields.
+
+### Output format
+Write the updated spike JSON to stdout, nothing else. Budget: 3 bounces per invocation.
+
+---
+
+## General rules
+- **Schema compliance is mandatory.** If your output fails AJV validation, you bounce and try again. Budget: 3 bounces per invocation.
+- **No side-effects on the filesystem.** Don't write files. The orchestrator persists your output.
+- **No tool use beyond reading.** v0.5 limits Researcher to doc-reading; web search and external tools are future work.

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

@@ -0,0 +1,74 @@
+---
+name: cloverleaf-breakdown
+description: Invoke the Plan agent (operation=breakdown) to decompose an approved RFC + completed spikes into a Plan with task_dag + inline tasks. Transitions Plan drafting → gate-pending (task_batch_gate). Usage — /cloverleaf-breakdown <RFC-ID>.
+---
+
+# Cloverleaf — Plan breakdown
+
+The user has invoked this skill with an RFC-ID (e.g., `CLV-009`).
+
+## Steps
+
+1. Capture `<RFC-ID>` as `$RFC_ID`. If missing, report usage and stop.
+
+2. Load and verify the RFC is in status `approved`:
+   ```
+   cloverleaf-cli load-rfc <repo_root> <RFC-ID>
+   ```
+   If `status !== "approved"`, report "RFC must be approved before breakdown" and stop.
+
+3. Collect all completed Spikes for this RFC. For each `.cloverleaf/spikes/*.json`:
+   - Parse the JSON.
+   - If `parent_rfc.id === $RFC_ID` AND `parent_rfc.project === <rfc.project>` AND `status === "completed"`: include in the SPIKES array.
+   - If zero matches, SPIKES is `[]`.
+
+4. Load discovery config:
+   ```bash
+   CFG=$(cloverleaf-cli discovery-config --repo-root <repo_root>)
+   DOC_CTX=$(echo "$CFG" | jq -r .docContextUri)
+   PROJECT_ID=$(echo "$CFG" | jq -r .projectId)
+   ```
+
+5. Compute the next work-item ID (this is the Plan's ID):
+   ```
+   PLAN_ID=$(cloverleaf-cli next-work-item-id <repo_root> $PROJECT_ID)
+   ```
+
+6. Dispatch the Plan subagent via the Task tool:
+   - `subagent_type`: `general-purpose`
+   - `model`: `sonnet`
+   - Prompt: contents of `$(cloverleaf-cli plugin-root)/prompts/plan.md`, with placeholders:
+     - `{{rfc}}` → the full RFC JSON
+     - `{{spikes}}` → the SPIKES JSON array
+     - `{{doc_context_uri}}` → `$DOC_CTX`
+     - `{{repo_root}}` → absolute path to the current repo
+     - `{{path_rules}}` → `null` (v0.5 does not auto-populate path_rules; defer to v0.6)
+
+   In the subagent context, also supply a hint that `next_id_base === $PLAN_ID`, so task IDs in `tasks[]` start at `PLAN_ID + 1`. The Plan agent allocates its own ID as `next_id_base` and task IDs sequentially after.
+
+7. Parse subagent response — expected JSON conforming to `plan.schema.json`. Required fields: `id, type: "plan", status: "drafting", owner, project, parent_rfc, task_dag (edge-based), tasks (inline Task docs, status=pending)`. 3-bounce budget per invocation.
+
+8. Ensure output `plan.id === $PLAN_ID`, `project === $PROJECT_ID`, `parent_rfc === { project: <rfc.project>, id: $RFC_ID }`. If the subagent drifted, override these before save.
+
+9. Save the Plan:
+   ```
+   cloverleaf-cli save-plan <repo_root> /tmp/plan-$PLAN_ID.json
+   ```
+
+10. Transition drafting → gate-pending:
+    ```
+    cloverleaf-cli advance-plan <repo_root> $PLAN_ID gate-pending agent task_batch_gate
+    ```
+
+11. Commit:
+    ```bash
+    git add .cloverleaf/plans/ .cloverleaf/events/
+    git commit -m "cloverleaf: plan $PLAN_ID for RFC $RFC_ID → gate-pending"
+    ```
+
+12. Print the Plan ID.
+
+## Notes
+
+- Tasks from `plan.tasks[]` are NOT yet materialised on disk. Materialisation happens only after a human approves via `/cloverleaf-gate $PLAN_ID approve`, which transitions the Plan to `approved`, at which point the orchestrator runs `cloverleaf-cli materialise-tasks`.
+- If the RFC has no completed spikes (`unknowns[]` was empty), SPIKES is `[]` and the Plan agent works from the RFC alone.

package/skills/cloverleaf-discover/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: cloverleaf-discover
+description: End-to-end Discovery orchestrator. Drives RFC → (Spikes) → Plan → gates → task materialisation. Blocks on human gate decisions (rfc_strategy_gate, task_batch_gate). On Plan approval, materialises tasks and asks whether to kick off /cloverleaf-run on the first DAG root. Usage — /cloverleaf-discover <brief-file>.
+---
+
+# Cloverleaf — discover (Discovery orchestrator)
+
+The user has invoked this skill with a brief file path (e.g., `docs/briefs/cross-browser-ui-review.md`).
+
+## Branch discipline
+
+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 (in-session)
+
+- **Researcher and Plan agent bounces are budgeted inside the sub-skills** (`/cloverleaf-draft-rfc`, `/cloverleaf-spike`, `/cloverleaf-breakdown`), each with a 3-bounce per-invocation budget. The orchestrator invokes each sub-skill once per step — if a sub-skill exhausts its budget, it halts, and the orchestrator treats that as a hard halt and dumps state.
+- **Revise loops are budgeted in the orchestrator:**
+  ```
+  MAX_REVISE_LOOPS = 3
+  ```
+  Resets on each `/cloverleaf-discover` invocation.
+
+## Steps
+
+1. Capture `<brief-file>` as `$BRIEF_FILE`. Verify file exists:
+   ```bash
+   [ -f "$BRIEF_FILE" ] || { echo "Brief file not found: $BRIEF_FILE" >&2; exit 1; }
+   ```
+
+2. Verify branch is `main`:
+   ```bash
+   [ "$(git rev-parse --abbrev-ref HEAD)" = "main" ] || { echo "Run /cloverleaf-discover from main" >&2; exit 1; }
+   ```
+
+3. **Create the RFC** — inline `/cloverleaf-new-rfc $BRIEF_FILE` steps. Capture the printed RFC ID as `$RFC_ID`.
+
+   Initialise revise loop counter:
+   ```
+   revise_loops = 0
+   ```
+
+4. **Draft RFC (Researcher draftRfc)** — inline `/cloverleaf-draft-rfc $RFC_ID` steps. Researcher runs with a per-invocation bounce budget (3 bounces inside draft-rfc).
+   - On bounce exhaustion (draft-rfc exits non-zero): dump state to `.cloverleaf/runs/$RFC_ID/discover-crash.json` and halt.
+   - Reload the RFC. Its new status is either `spike-in-flight` (unknowns non-empty) or `planning` (unknowns empty).
+
+5. **Conditional on RFC status after step 4:**
+   - If `planning`: skip the spike loop below; proceed to step 6.
+   - If `spike-in-flight`: run every pending spike linked to this RFC:
+     ```bash
+     for each spike in .cloverleaf/spikes/*.json where parent_rfc.id === $RFC_ID AND status === "pending":
+       inline /cloverleaf-spike <SPIKE_ID> steps.
+     ```
+
+     If `/cloverleaf-spike` exits non-zero or leaves the spike in a non-`completed` status after returning, treat that as bounce exhaustion: dump state to `.cloverleaf/runs/$RFC_ID/discover-crash.json` (including the spike ID) and halt. The orchestrator does NOT resume partially-run spike trees — if any spike is unresolved, the whole Discovery halts.
+
+     After all spikes complete:
+
+     1. Transition RFC spike-in-flight → drafting:
+        ```
+        cloverleaf-cli advance-rfc <repo_root> $RFC_ID drafting agent
+        ```
+     2. Re-invoke `/cloverleaf-draft-rfc $RFC_ID` — Researcher sees the completed spikes and may revise the RFC body. draft-rfc itself re-transitions the RFC to `spike-in-flight` (if new unknowns emerge — should not happen the second time since spikes were answered) or `planning` (expected path).
+
+     Rationale: redundant redraft is cheap; avoids introducing an off-contract "rfc_revision_required" boolean. The human gate at step 6 catches any missed revisions.
+
+6. **Gate: rfc_strategy_gate** — transition RFC to gate-pending:
+   ```
+   cloverleaf-cli advance-rfc <repo_root> $RFC_ID gate-pending agent rfc_strategy_gate
+   ```
+
+   Prompt human (blocking readline):
+   ```
+   RFC $RFC_ID at rfc_strategy_gate: approve / reject / revise [reason]? > _
+   ```
+
+   Parse input. On:
+   - `approve` → inline `/cloverleaf-gate $RFC_ID approve` steps. Continue to step 7.
+   - `reject [reason]` → inline `/cloverleaf-gate $RFC_ID reject [reason]` steps. Exit with summary.
+   - `revise [reason]` → inline `/cloverleaf-gate $RFC_ID revise [reason]` steps. `revise_loops += 1`. If `revise_loops >= MAX_REVISE_LOOPS`, dump state and halt. Else loop back to step 4.
+
+7. **Plan breakdown** — inline `/cloverleaf-breakdown $RFC_ID` steps. Per-invocation bounce budget (3 bounces inside breakdown). Capture `$PLAN_ID`. On bounce exhaustion: dump state and halt.
+
+8. **Gate: task_batch_gate** — Plan is already in `gate-pending` (set by breakdown). Prompt:
+   ```
+   PLN $PLAN_ID at task_batch_gate: approve / reject [reason]? > _
+   ```
+
+   On:
+   - `approve` → inline `/cloverleaf-gate $PLAN_ID approve` steps. Continue.
+   - `reject [reason]` → inline `/cloverleaf-gate $PLAN_ID reject [reason]` steps. Exit with summary.
+
+9. **Materialise tasks**:
+   ```bash
+   OUT=$(cloverleaf-cli materialise-tasks <repo_root> $PLAN_ID)
+   TASK_IDS=$(echo "$OUT" | jq -r '.task_ids[]')
+   ```
+
+   On materialise-tasks failure (cycle detected, or AJV validation error):
+   - The error message from `cloverleaf-cli` identifies the failing task.
+   - `materialiseTasksFromPlan` is atomic: the cycle-check and AJV pre-validation run BEFORE any file write, so no task files were created.
+   - The Plan remains in `approved` status (the gate was legitimately approved; the materialisation issue is with the Plan's own task DAG, not the gate decision).
+   - Dump state to `.cloverleaf/runs/$PLAN_ID/materialise-crash.json` and halt.
+   - Operator investigation typically leads to a new `/cloverleaf-breakdown` run to produce a corrected Plan (the rejected path is via the ORIGINAL gate, not a post-approval state correction).
+
+10. **Compute DAG roots**:
+    ```bash
+    PLAN_JSON=$(cloverleaf-cli load-plan <repo_root> $PLAN_ID)
+
+    # DAG roots = nodes whose id never appears as `to.id` in any edge.
+    # v0.5 picks the FIRST root only; multi-root concurrent Delivery is v0.6.
+    FIRST_ROOT=$(echo "$PLAN_JSON" | jq -r '
+      (.task_dag.edges | map(.to.id)) as $targets
+      | [.task_dag.nodes[] | select(.id as $n | ($targets | index($n)) | not) | .id][0]
+    ')
+    ```
+
+    v0.5 simplified rule: pick the FIRST root only (first `nodes[]` entry whose `id` does not appear in any `edges[].to.id`). Defer multi-root walk to v0.6.
+
+11. **Prompt to kick off first root** (blocking readline):
+    ```
+    N tasks materialised: $TASK_IDS.
+    DAG roots: $FIRST_ROOT.
+    Run first root via /cloverleaf-run now? [y/N] > _
+    ```
+
+    On `y` or `yes` (case-insensitive): inline `/cloverleaf-run <FIRST_ROOT>` steps. On anything else: exit with summary.
+
+12. **Exit summary**:
+    - RFC ID + final status
+    - Spike IDs + findings summary (if any)
+    - Plan ID + task count
+    - Materialised task IDs
+    - Whether first root was invoked (and its outcome if so)
+
+## Notes
+
+- v0.5 prompts only for the FIRST DAG root. Multi-root concurrent Delivery is v0.6 scope.
+- All bounces and revise loops halt cleanly with a state dump at `.cloverleaf/runs/<RFC_ID>/discover-crash.json`. No partial work is left in an inconsistent state — the gate_decision events and work-item status are always coherent.
+- The readline prompts are compatible with the user's session-bridging tool for automated dogfooding.

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

@@ -0,0 +1,99 @@
+---
+name: cloverleaf-draft-rfc
+description: Invoke the Researcher agent (operation=draftRfc) to populate an RFC body from its brief. Emits zero or more Spike work items from the RFC's unknowns[]. Transitions the RFC drafting → spike-in-flight (if unknowns exist) or drafting → planning (if no unknowns). Usage — /cloverleaf-draft-rfc <RFC-ID>.
+---
+
+# Cloverleaf — draft RFC
+
+The user has invoked this skill with an RFC-ID (e.g., `CLV-009`).
+
+## Steps
+
+1. Capture `<RFC-ID>` as `$RFC_ID`. If missing, report usage and stop.
+
+2. Load the RFC:
+   ```
+   cloverleaf-cli load-rfc <repo_root> <RFC-ID>
+   ```
+   Parse the JSON. Verify `status === "drafting"`. If not, report and stop.
+
+3. Load the discovery config:
+   ```bash
+   CFG=$(cloverleaf-cli discovery-config --repo-root <repo_root>)
+   DOC_CTX=$(echo "$CFG" | jq -r .docContextUri)
+   ```
+
+4. Gather re-draft context (optional — used when re-invoked after spikes):
+   - `PRIOR_RFC`: the current RFC JSON (for a re-draft, same content)
+   - `COMPLETED_SPIKES`: for each spike ref linked to this RFC (via spike's `parent_rfc` field), if `status === "completed"`, include its findings/recommendation. Build a JSON array. If none, use `[]`.
+
+   Find all spikes for this RFC by scanning `.cloverleaf/spikes/*.json` for files whose `parent_rfc.id === $RFC_ID`. Use jq. If none, the array is empty.
+
+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 substituted:
+     - `{{operation}}` → `draftRfc`
+     - `{{brief}}` → the RFC's `problem` field (seeded by `/cloverleaf-new-rfc`)
+     - `{{doc_context_uri}}` → `$DOC_CTX`
+     - `{{repo_root}}` → absolute path to the current repo
+     - `{{prior_rfc}}` → `PRIOR_RFC` JSON (or the literal string `null` for first draft)
+     - `{{completed_spikes}}` → `COMPLETED_SPIKES` JSON array (or `[]`)
+     - `{{spike}}` → (unused for draftRfc; substitute `null`)
+
+6. Parse subagent's response: expected JSON conforming to `rfc.schema.json`. Required fields: `id`, `type: "rfc"`, `status: "drafting"`, `owner`, `project`, `title`, `problem`, `solution`, `unknowns` (array of strings), `acceptance_criteria`, `out_of_scope`.
+
+   If output fails schema validation: bounce. Budget: 3 bounces per invocation. On budget exhaustion: report and stop without advancing state.
+
+7. Ensure output `id === $RFC_ID` and `project === <original>`. If the subagent changed them, override back.
+
+8. Save the populated RFC:
+   ```bash
+   cloverleaf-cli save-rfc <repo_root> /tmp/rfc-draft-$RFC_ID.json
+   ```
+
+9. Inspect `rfc.unknowns[]`:
+
+   **If `unknowns.length > 0`:** create one Spike per unknown:
+   ```bash
+   for unknown in rfc.unknowns:
+     SPIKE_ID=$(cloverleaf-cli next-work-item-id <repo_root> <project>)
+     cat > /tmp/spike-$SPIKE_ID.json <<EOF
+     {
+       "type": "spike",
+       "project": "<project>",
+       "id": "$SPIKE_ID",
+       "status": "pending",
+       "owner": { "kind": "agent", "id": "researcher" },
+       "title": "<first 80 chars of unknown>",
+       "parent_rfc": { "project": "<project>", "id": "$RFC_ID" },
+       "question": "<unknown>",
+       "method": "research"
+     }
+     EOF
+     cloverleaf-cli save-spike <repo_root> /tmp/spike-$SPIKE_ID.json
+   ```
+
+   Then transition RFC:
+   ```
+   cloverleaf-cli advance-rfc <repo_root> <RFC-ID> spike-in-flight agent
+   ```
+
+   **If `unknowns.length === 0`:** transition RFC directly to planning:
+   ```
+   cloverleaf-cli advance-rfc <repo_root> <RFC-ID> planning agent
+   ```
+
+10. Clean up temp files. Commit state files under `.cloverleaf/`:
+    ```bash
+    git add .cloverleaf/rfcs/ .cloverleaf/spikes/ .cloverleaf/events/
+    git commit -m "cloverleaf: draft RFC $RFC_ID + spike emission"
+    ```
+
+11. Report: RFC body populated; N spikes created (list IDs); RFC status now `spike-in-flight` or `planning`.
+
+## Notes
+
+- This skill does NOT prompt for human input. It's a pure agent step.
+- The orchestrator (`/cloverleaf-discover`) invokes this plus manages bounces and gates.
+- For a re-draft after spikes complete, invoke this skill again with the same RFC-ID — it will pick up completed spikes and may revise the RFC body.