@cloverleaf/reference-impl 0.12.0 → 0.13.0

package/lib/events.ts

@@ -13,7 +13,6 @@ export interface StatusTransitionParams {
   to: string;
   actor: 'agent' | 'human' | 'system';
   gate?: string;
-  path?: 'fast_lane' | 'full_pipeline';
 }
 
 export interface GateDecisionParams {
@@ -31,11 +30,8 @@ function actorObject(kind: 'agent' | 'human' | 'system'): { kind: string; id: st
   return { kind, id };
 }
 
-export function formatReason(opts: { gate?: string; path?: string }): string | undefined {
-  const parts: string[] = [];
-  if (opts.gate) parts.push(`gate=${opts.gate}`);
-  if (opts.path) parts.push(`path=${opts.path}`);
-  return parts.length > 0 ? parts.join('; ') : undefined;
+export function formatReason(opts: { gate?: string }): string | undefined {
+  return opts.gate ? `gate=${opts.gate}` : undefined;
 }
 
 /**
@@ -56,8 +52,8 @@ export function emitStatusTransition(repoRoot: string, params: StatusTransitionP
   const filename = `${workItemId}-${seqStr}-status.json`;
   const filePath = join(eventsDir(repoRoot), filename);
 
-  // Build reason from gate and/or path if provided (schema only allows reason, not gate/path at top level).
-  const reason = formatReason({ gate: params.gate, path: params.path });
+  // Build reason from the gate if provided (the schema allows only `reason` at top level).
+  const reason = formatReason({ gate: params.gate });
 
   const doc: Record<string, unknown> = {
     event_id: randomUUID(),

package/lib/ids.ts

@@ -22,6 +22,13 @@ export function nextEventId(repoRoot: string, workItemId: string): number {
   // simultaneously. A global per-project counter (the pre-v0.6 scheme) produced
   // filename collisions when the walker merged sibling feature branches. Per-work-item
   // scoping means each task's counter is independent; merges union cleanly.
+  //
+  // The `(\d+)` segment is load-bearing, not cosmetic: `.cloverleaf/events/` in
+  // long-lived repos also contains pre-v0.6 files named `<PROJECT>-<NNN>-status.json`
+  // (a global counter), whose names collide with the task-id namespace — e.g.
+  // `CLV-109-status.json` is the 109th project event, not an event for task CLV-109.
+  // Loosening this regex to a bare prefix match would fold unrelated tasks' history
+  // into a task's counter, including transitions through states retired in 0.8.0.
   const re = new RegExp(`^${escapeRegex(workItemId)}-(\\d+)-(status|gate)\\.json$`);
   const nums = readdirSync(dir)
     .map((f) => f.match(re))

package/lib/qa-rules.ts

@@ -18,19 +18,40 @@ function loadDefaultRules(): QaRule[] {
   return Array.isArray(doc.rules) ? doc.rules : [];
 }
 
-export function loadQaRulesConfig(repoRoot: string): QaRule[] {
+export interface QaRulesDocument {
+  rules: QaRule[];
+}
+
+/**
+ * The qa-rules document in the shape the prompts consume it: the `{ rules: [...] }`
+ * object, not a bare array. `reviewer.md` ({{test_rules}}), `implementer.md`
+ * ({{test_rules}}) and `qa.md` ({{qa_rules}}) all document the token as an object —
+ * 0.10.1 shipped a fix precisely because `qa.md` had described it as an array, and an
+ * agent iterating a non-existent top-level array is the bug that fix closed. Callers
+ * substituting one of those tokens must stringify THIS, never `loadQaRulesConfig()`.
+ *
+ * Precedence matches what the standalone skills `cat`: the consumer's
+ * `.cloverleaf/config/qa-rules.json` when it exists and parses to a `rules` array,
+ * otherwise the packaged default.
+ */
+export function loadQaRulesDocument(repoRoot: string): QaRulesDocument {
   const consumerPath = join(repoRoot, '.cloverleaf', 'config', 'qa-rules.json');
   if (existsSync(consumerPath)) {
     try {
       const doc = JSON.parse(readFileSync(consumerPath, 'utf-8')) as { rules?: QaRule[] };
       if (Array.isArray(doc.rules)) {
-        return doc.rules;
+        return { rules: doc.rules };
       }
     } catch {
       // fall through
     }
   }
-  return loadDefaultRules();
+  return { rules: loadDefaultRules() };
+}
+
+/** The rules array alone, for callers that select/execute commands rather than prompt with them. */
+export function loadQaRulesConfig(repoRoot: string): QaRule[] {
+  return loadQaRulesDocument(repoRoot).rules;
 }
 
 export function selectTestCommands(changedFiles: string[], rules: QaRule[]): QaRule[] {

package/lib/task.ts

@@ -53,16 +53,16 @@ export function advanceStatus(
   taskId: string,
   toStatus: string,
   actor: 'agent' | 'human',
-  options: { gate?: string; path?: 'fast_lane' | 'full_pipeline' } = {}
+  options: { gate?: string } = {}
 ): TaskDoc {
   let task = loadTask(repoRoot, taskId);
   const from = task.status;
   const sm = loadStateMachine('task');
 
-  const targetTransition = sm.transitions.find((t) => t.from === from && t.to === toStatus);
-
-  // Security-gate writeback: classify the task's security and upgrade if needed.
-  if (targetTransition?.security_gate) {
+  // Security classification at council entry: a declared-low task whose diff touches a
+  // sensitive path is upgraded to security_class:high so the delivery council runs its
+  // blocking security member. (v0.8.0: replaces the retired security_gate FSM annotation.)
+  if (from === 'documenting' && toStatus === 'council') {
     let classification;
     try {
       classification = classifyTaskSecurity(repoRoot, taskId);
@@ -96,17 +96,12 @@ export function advanceStatus(
     }
   }
 
-  const riskClass: 'low' | 'high' =
-    options.path === 'fast_lane' ? 'low'
-    : options.path === 'full_pipeline' ? 'high'
-    : (task.risk_class ?? 'low');
-
   const workItemForValidator: SMTask = {
     type: 'task',
     id: task.id,
     project: task.project,
     status: task.status,
-    risk_class: riskClass,
+    risk_class: task.risk_class ?? 'low',
     security_class: task.security_class,
     security_review_verdict: task.security_review_verdict,
     context: { rfc: { project: task.project, id: task.id } },
@@ -114,12 +109,7 @@ export function advanceStatus(
     acceptance_criteria: task.acceptance_criteria,
   };
 
-  const resetsVerdict = targetTransition?.resets_security_verdict === true;
-  const proposed: TaskDoc = {
-    ...task,
-    status: toStatus,
-    ...(resetsVerdict ? { security_review_verdict: null } : {}),
-  };
+  const proposed: TaskDoc = { ...task, status: toStatus };
 
   advanceWorkItemStatus({
     repoRoot,
@@ -134,23 +124,7 @@ export function advanceStatus(
     save: (p) => saveTask(repoRoot, p as TaskDoc),
     proposed,
     gate: options.gate,
-    path: options.path,
   });
 
-  // After a successful status change + verdict reset, emit a single commit covering both.
-  if (resetsVerdict) {
-    const taskFilePath = join(tasksDir(repoRoot), `${taskId}.json`);
-    try {
-      execFileSync('git', ['-C', repoRoot, 'add', taskFilePath], { stdio: 'pipe' });
-      execFileSync(
-        'git',
-        ['-C', repoRoot, 'commit', '-m', `cloverleaf: ${taskId} status ${from} → ${toStatus}; security_review_verdict → null (rework)`],
-        { stdio: 'pipe' }
-      );
-    } catch {
-      // No-op: commit is best-effort when running outside a git repo (e.g., test environments).
-    }
-  }
-
   return proposed;
 }

package/lib/work-item.ts

@@ -26,7 +26,6 @@ export interface AdvanceWorkItemParams<T> {
   save: (proposed: T & { status: string }) => void;
   proposed: T;
   gate?: string;
-  path?: 'fast_lane' | 'full_pipeline';
 }
 
 export interface AdvanceWorkItemResult {
@@ -35,9 +34,9 @@ export interface AdvanceWorkItemResult {
 }
 
 export function advanceWorkItemStatus<T>(params: AdvanceWorkItemParams<T>): AdvanceWorkItemResult {
-  const { repoRoot, workItemType, project, id, from, to, actor, stateMachine, validateFixture, save, gate, path } = params;
+  const { repoRoot, workItemType, project, id, from, to, actor, stateMachine, validateFixture, save, gate } = params;
 
-  const reason = formatReason({ gate, path });
+  const reason = formatReason({ gate });
   const event = {
     event_id: randomUUID(),
     event_type: 'status_transition' as const,
@@ -74,7 +73,6 @@ export function advanceWorkItemStatus<T>(params: AdvanceWorkItemParams<T>): Adva
     to,
     actor,
     gate,
-    path,
   });
 
   try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloverleaf/reference-impl",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Reference implementation of the Cloverleaf methodology as Claude Code skills. Implements the Tight Loop (Implementer + Reviewer).",
   "type": "module",
   "license": "MIT",
@@ -49,10 +49,10 @@
     "prepublishOnly": "node scripts/check-standard-prepped.mjs && npm test && npm run build"
   },
   "peerDependencies": {
-    "@cloverleaf/standard": "^0.7.1"
+    "@cloverleaf/standard": "^0.8.0"
   },
   "dependencies": {
-    "@cloverleaf/standard": "^0.7.0",
+    "@cloverleaf/standard": "^0.8.0",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
     "axe-core": "^4.10.0",
@@ -64,6 +64,8 @@
     "@types/node": "^22.0.0",
     "@types/pixelmatch": "^5.2.6",
     "@types/pngjs": "^6.0.5",
+    "@types/semver": "^7.8.0",
+    "semver": "^7.8.5",
     "tsx": "^4.19.0",
     "typescript": "^5.5.0",
     "vitest": "^2.0.0"

package/prompts/documenter.md

@@ -36,7 +36,7 @@ Inspect the diff. For each category below that matches, update the listed docs:
 
 | Diff touches | Docs to update |
 |---|---|
-| `standard/src/**`, `standard/schemas/**`, `standard/conformance/**` | `standard/CHANGELOG.md` (Unreleased), relevant `standard/docs/*.md` sections if behavior/conformance changed |
+| `standard/schemas/**`, `standard/state-machines/**`, `standard/validators/**`, `standard/agent-contracts/**`, `standard/conformance/**` | `standard/CHANGELOG.md` (Unreleased), relevant `standard/docs/*.md` sections if behavior/conformance changed |
 | `reference-impl/lib/**`, `reference-impl/skills/**`, `reference-impl/prompts/**` | `reference-impl/CHANGELOG.md` (Unreleased), `reference-impl/README.md` if public surface changed (new skill, CLI command, exported lib symbol) |
 | `site/src/**`, `site/public/**` | `site/CHANGELOG.md` ONLY if that file already exists; otherwise skip |
 | Root-level package additions, version bumps | Root `README.md`, root `CHANGELOG.md` |

package/prompts/implementer.md

@@ -25,11 +25,17 @@ You are the Cloverleaf Implementer agent. Your job: take a Task and produce work
    **Scope nudge.** Your declared scope is `task.scope.files_touched`. You may freely modify any file listed there. If you discover during implementation that you need to touch a file outside that list, you may do so only if no sibling task in the same Plan declares that file — the walker auto-extends your scope on merge. If a file you need is already declared by a sibling task, that is a contested modification: stop, surface the conflict to the human, and do not merge. The walker enforces this at merge time and will refuse contested merges; auto-resolution is never attempted.
 
 2. If `feedback` is present, re-read each finding; plan how to address them. If the prior bounce came from a chair council (`.cloverleaf/runs/<task.id>/council/task.review.json` has `rule: "chair"`), prioritize the members listed in its `forward` array and the chair's `rationale`.
-3. Create a new branch named `cloverleaf/<task.id>` from `base_branch` using `git checkout -b cloverleaf/<task.id>`.
+3. Get onto the task's branch, `cloverleaf/<task.id>`:
+   - If it does **not** exist, create it from `base_branch`: `git checkout -b cloverleaf/<task.id>`.
+   - If it **does** exist, you are reworking after a council bounce. Check it out — `git checkout cloverleaf/<task.id>` — and re-implement in place. **Never recreate or reset the branch:** it already carries earlier work, including the Documenter's doc commits, and rebuilding it from `base_branch` silently destroys them.
 4. Implement the code + tests needed to satisfy every acceptance criterion.
 5. Run the project's tests. Your test rules are provided as `{{test_rules}}` — a JSON object `{ rules: [...] }` whose `rules` is a list of `{cwd, match, command}` entries; each `match` is a list of glob patterns. For each rule whose `match` covers a file you changed, run its `command` in its `cwd`. All must pass. (If no rule matches your changes, there is nothing to run.)
+
+   Run your verification to completion **before returning**. If a command may exceed the default tool timeout, pass an explicit longer timeout rather than backgrounding it and returning early — a prose "I'll wait" message is not a valid result, and the orchestrator has no defined recovery for a non-conforming response. (This project's own `reference-impl` suite takes roughly five minutes, which exceeds the default.)
+
+   **Capture suite results safely:** redirect output to a file and check the exit code — `<command> > /tmp/suite.log 2>&1; echo "EXIT=$?"` — and never pipe the run through `| tail` or `| head`. A pipe reports the *last* command's exit status, so a failing suite reads as success.
 6. Stage and commit your changes with message `feat: <task.title> [<task.id>]`.
-7. Return a structured JSON result to stdout:
+7. Return a structured JSON result as your final message — **exactly one JSON object and nothing else**, no prose before or after it, no markdown fence commentary:
 
 ```json
 {

package/prompts/qa.md

@@ -43,18 +43,19 @@ The Standard's QA contract requires a `preview_uri`. You were passed the sentine
 
 3. If no rules match (e.g., the diff only changes `.cloverleaf/**` or tests unrelated to any package), skip with a `pass` verdict — nothing testable in this diff:
    ```json
-   {"verdict": "pass", "summary": "No testable packages changed.", "findings": [], "results": {"passed": 0, "failed": 0, "total": 0}}
+   {"verdict": "pass", "summary": "No testable packages changed. Test counts: passed 0, failed 0, total 0.", "findings": []}
    ```
 
 4. For each queued command:
    - Run it in `"$TMPDIR/<cwd>"`
    - Capture stdout, stderr, exit code
+   - **Capture suite results safely:** redirect output to a file and check the exit code — `<command> > /tmp/suite.log 2>&1; echo "EXIT=$?"` — and never pipe the run through `| tail` or `| head`. A pipe reports the *last* command's exit status, so a failing suite reads as success.
    - Parse test output to extract `passed`, `failed`, `total`:
      - Exit code is the universal signal: exit 0 = the command's checks passed; non-zero = failed.
      - When the output format is recognized, also extract counts, e.g. Vitest (`Tests N passed | M failed`), pytest (`N passed, M failed`), or a plain build/lint (exit 0 → `{passed: 1, failed: 0, total: 1}`).
    - On failure, collect up to 10 failure names/messages as findings with `severity: "error"` and `rule: "qa.<suite>.<test-name>"`
 
-5. Aggregate results: sum `passed`, `failed`, `total` across all runs.
+5. Aggregate results: sum `passed`, `failed`, `total` across all runs, and state them at the end of `summary`. Do not add a top-level `results` key — the feedback envelope schema forbids properties beyond `verdict`, `summary` and `findings`.
 
 6. Compute verdict:
    - `pass` — every command exited 0 AND aggregated `failed === 0`
@@ -94,6 +95,7 @@ The CLI creates the output directory.
 
 In the feedback you emit, include the report as an attachment on a single info-level finding (or on whichever summary finding you already emit):
 
+<!-- cloverleaf-schema: feedback.schema.json#/$defs/finding -->
 ```json
 {
   "severity": "info",
@@ -114,7 +116,7 @@ Respond with exactly one JSON object and nothing else:
 ```json
 {
   "verdict": "pass" | "bounce" | "escalate",
-  "summary": "<one-sentence summary>",
+  "summary": "<one-sentence summary, ending with the aggregate counts, e.g. 'Test counts: passed 153, failed 0, total 153.'>",
   "findings": [
     {
       "severity": "error",
@@ -122,11 +124,6 @@ Respond with exactly one JSON object and nothing else:
       "message": "<test failure message>",
       "location": "<file:line if known>"
     }
-  ],
-  "results": {
-    "passed": <integer>,
-    "failed": <integer>,
-    "total": <integer>
-  }
+  ]
 }
 ```

package/prompts/reviewer.md

@@ -21,13 +21,13 @@ You are the Cloverleaf Reviewer agent. Your job: perform a fresh-eyes review of
    Run this as the first executable step before anything else. Session B sessions may inherit an arbitrary `cwd` from the walker harness; this anchors you at the repo root.
 
 1. Read the task's `acceptance_criteria` and `definition_of_done`.
-2. Run `git diff <base_branch>..<branch> --stat` and `git diff <base_branch>..<branch>` to see the change.
+2. Run `git diff <base_branch>..<branch> --stat -- ':(exclude).cloverleaf/'` and `git diff <base_branch>..<branch> -- ':(exclude).cloverleaf/'` to see the change. Excluding `.cloverleaf/` matters: the orchestrator commits FSM state to `<base_branch>` while the feature branch stays behind, so an unfiltered two-dot diff shows the branch "deleting" event files and reverting the task's `status`. That is branch/base divergence, not implementer drift — never bounce a task for it.
 3. For each acceptance criterion, determine whether the diff satisfies it. Note any unsatisfied criteria as findings.
 4. Check for defects: missing tests, obvious logic errors, security issues, hygiene problems.
 5. Decide verdict:
    - `pass` if every acceptance criterion is satisfied and no blocking defects exist.
    - `bounce` otherwise.
-6. Return a feedback envelope (per `feedback.schema.json`) to stdout as JSON:
+6. Return a feedback envelope (per `feedback.schema.json`) as your final message — **exactly one JSON object and nothing else**:
 
 ```json
 {
@@ -67,6 +67,8 @@ A `pass` verdict MAY have an empty `findings` array or omit it. A `bounce` verdi
   Use `--detach` with a SHA rather than a branch name: when running inside a walker worktree, the feature branch (and main) may already be checked out in another worktree, causing `git worktree add` to fail with "fatal: branch … is already checked out". Detaching at a SHA bypasses this constraint entirely.
 
   This keeps `.cloverleaf/` on main intact.
+
+  **Capture suite results safely:** redirect output to a file and check the exit code — `<command> > /tmp/suite.log 2>&1; echo "EXIT=$?"` — and never pipe the run through `| tail` or `| head`. A pipe reports the *last* command's exit status, so a failing suite reads as success.
 - **Loading or running a module directly (TypeScript projects).** If your project is TypeScript, do not improvise `node -e "import('./lib/x.js')"` to spot-check a module — sources are `.ts` and the build emits `.mjs`, so a bare `.js` import resolves to neither. Use `npx tsx` instead (resolves `.ts` sources and `.js`-style import specifiers):
 
   ```bash

package/prompts/ui-reviewer.md

@@ -25,13 +25,53 @@ Run this as the first executable step before anything else. Session B sessions m
 
 You operate in two filesystem locations — keep them straight:
 
-- `<worktree>` — the ephemeral worktree at `$WT` (set up in step 2 of the Runtime procedure). You run the dev server here and execute Playwright here. Any standalone `.mjs` driver scripts must be placed INSIDE `$WT/site/` so that Node can resolve `playwright` from `$WT/site/node_modules/`; do NOT write them outside the worktree where no `node_modules` is present.
+- `<worktree>` — the ephemeral worktree at `$WT` (set up in step 2 of the Runtime procedure). You run the dev server here and drive Playwright against it. A standalone `.mjs` driver may live wherever you find convenient — its imports are anchored at the plugin root, not at its own directory (see "Resolving your dependencies" below) — but you MUST delete any driver you write during teardown (step 13).
 - `<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 `$WT`.**
 
 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.
 
+## Resolving your dependencies
+
+`playwright`, `axe-core`, `pixelmatch` and `pngjs` are runtime dependencies of `@cloverleaf/reference-impl`, so they are installed under the **plugin root** — never under the repository you are reviewing. The repo's UI directory declares none of them, and `prep-worktree` copies no `node_modules` into `$WT/site/`. **A bare specifier therefore cannot resolve, from any directory**: `import 'playwright'` and `import 'axe-core'` both fail with `ERR_MODULE_NOT_FOUND` regardless of where your driver sits.
+
+Export the plugin root once, before you run anything:
+
+```bash
+export CLOVERLEAF_PLUGIN_ROOT="$(npx cloverleaf-cli plugin-root)"
+```
+
+Then anchor every import at it. `createRequire` resolves each package by name from the plugin root, so you never hard-code a package's internal file layout:
+
+```javascript
+import { createRequire } from 'node:module';
+
+const PLUGIN_ROOT = process.env.CLOVERLEAF_PLUGIN_ROOT;
+const require = createRequire(PLUGIN_ROOT + '/');
+
+const { chromium, firefox, webkit } = require('playwright');
+const axe = require('axe-core');
+```
+
+Cloverleaf's own helpers are ESM, one `dist/<module>.mjs` per `lib/<module>.ts`. Import them by absolute path:
+
+```javascript
+const { compareVisual }     = await import(`${PLUGIN_ROOT}/dist/visual-diff.mjs`);
+const { slugifyRoute }      = await import(`${PLUGIN_ROOT}/dist/route-slug.mjs`);
+const { dedupeAxeFindings } = await import(`${PLUGIN_ROOT}/dist/axe-dedupe.mjs`);
+const { applyMaxCombinationsCap, buildBrowserEscalationFinding } =
+  await import(`${PLUGIN_ROOT}/dist/ui-browser.mjs`);
+```
+
+If an import fails, fix the anchor. Do **not** relocate the driver, do **not** add packages to the reviewed repo's `package.json`, and do **not** `npm install` anything into a scratch directory — none of that changes what resolves, and editing the repo's manifest would pollute the diff under review.
+
+Keep whatever path you pick for the driver in a shell variable — the steps below call it `$DRIVER` — so teardown can delete it:
+
+```bash
+DRIVER="$WT/site/ui-review-driver.mjs"   # any path works; this one is also swept up with the worktree
+```
+
 ## Scope (v0.5)
 
 - **Browsers**: the reviewer runs separate Playwright sessions for each engine listed in `{{ui_review_config}}.browsers` (e.g., `["chromium", "webkit", "firefox"]`). Browser is the **outermost** loop, wrapping the viewport × route loops.
@@ -61,7 +101,15 @@ The cap enforcement helper is available in `lib/ui-browser.ts` as `applyMaxCombi
 
 ## Playwright cache
 
-The `PLAYWRIGHT_BROWSERS_PATH` environment variable is set to `~/.cache/ms-playwright` before you are invoked. Before launching each browser session, verify that the required engine binary exists in `PLAYWRIGHT_BROWSERS_PATH`. If a browser binary is absent, return `verdict: "escalate"` with a synthetic finding per missing engine:
+Playwright keeps its engine binaries in a shared cache outside the worktree, so a review never re-downloads ~300 MB. Establish that location yourself — do not assume a caller set it for you:
+
+```bash
+export PLAYWRIGHT_BROWSERS_PATH="${PLAYWRIGHT_BROWSERS_PATH:-$HOME/.cache/ms-playwright}"
+```
+
+This defers to a dispatcher or operator who already set the variable (a non-default cache directory is a supported override) and falls back to Playwright's own default otherwise. Write `$HOME`, not `~`: a tilde inside double quotes is not expanded, and `"~/.cache/ms-playwright"` would create a literal `~` directory.
+
+Before launching each browser session, verify that the required engine binary exists in `$PLAYWRIGHT_BROWSERS_PATH`. If a browser binary is absent, return `verdict: "escalate"` with a synthetic finding per missing engine:
 
 ```
 "Playwright {engine} not installed. Run 'npx playwright install webkit firefox' on this machine."
@@ -84,17 +132,34 @@ Do not attempt to launch a missing engine — fail fast with `verdict: "escalate
    npx cloverleaf-cli prep-worktree {{repo_root}} "$WT"
    ```
 
-3. For this repo, UI lives in `site/` (or another directory if ui-paths.json scopes it elsewhere). Install dependencies and start the dev server:
+3. For this repo, UI lives in `site/` (or another directory if ui-paths.json scopes it elsewhere). Install dependencies and start the dev server.
+
+   **Capture command results safely:** redirect output to a file and check the exit code — `<command> > /tmp/step.log 2>&1; echo "EXIT=$?"` — and never pipe the run through `| tail` or `| head`. A pipe reports the *last* command's exit status, so a failing command reads as success.
+
+   **Disable dev-only overlay UI before the server starts.** A baseline must contain only what ships. Astro's dev server injects a dev toolbar over the bottom-centre of every page: it never reaches production, it occludes the exact region a bottom-of-page regression appears in, and it couples every baseline to the Astro version that drew it. It is in the DOM too, so the axe pass in step 8c would report the toolbar's own violations as the site's.
+
    ```bash
    cd "$WT/site"
-   npm ci
+   npm ci > /tmp/ui-npm-ci.log 2>&1; echo "EXIT=$?"
+   # EXIT must be 0 before you go on. On any other value, read /tmp/ui-npm-ci.log
+   # to see why and return verdict `escalate` — do NOT continue with a broken install.
+   npx astro preferences disable devToolbar > /tmp/ui-devtoolbar.log 2>&1; echo "EXIT=$?"
+   # Non-zero EXIT means this UI directory is not an Astro project — see below.
    npm run dev -- --port={{preview_port}} &
    SERVER_PID=$!
    ```
 
-   > **Playwright/driver script placement (Bug #3 fix) — applies to EVERY script you write, including retries and ad-hoc fallbacks:** place any standalone `.mjs` driver **inside the worktree** (e.g., `$WT/site/playwright-driver.mjs`) and run it from there (`node "$WT/site/playwright-driver.mjs"`). Node's ESM module resolution walks up from the script's own directory — a script placed anywhere outside the worktree (e.g. `/tmp`) cannot resolve the `playwright` import (or any `node_modules` package) and fails with `ERR_MODULE_NOT_FOUND`. If a driver errors and you retry, fix it in place in `$WT/site/` — never relocate or recreate it under `/tmp`.
+   `astro preferences disable devToolbar` is **project-scoped** by default: it writes into `$WT/site/.astro/`, which step 13 deletes along with the worktree, so it turns the toolbar off for this capture alone and nothing outside this run changes. Never pass `--global` — that writes to the operator's home directory and silently changes every other Astro project on the machine. Disable it before backgrounding the server, not after: Astro decides whether to inject the toolbar when the dev server boots.
+
+   If that command exits non-zero, this UI directory is **not an Astro project**. Disable that toolchain's own dev overlay instead. If it has none you can turn off, emit an `info` finding recording that the baseline may contain dev-only UI rather than capturing a contaminated one silently.
+
+   Apply the same capture rule to your driver run and to every other command whose success you judge:
+
+   ```bash
+   node "$DRIVER" > /tmp/ui-driver.log 2>&1; echo "EXIT=$?"
+   ```
 
-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`.
+4. Wait up to 30s for `http://localhost:{{preview_port}}/` to respond 200. If the server fails to start in 30s, run teardown (step 13) — `kill $SERVER_PID`, never a command-line pattern — and return verdict `escalate`.
 
 5. Determine the site base path:
    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.)
@@ -108,7 +173,7 @@ Do not attempt to launch a missing engine — fail fast with `verdict: "escalate
    - Use only the returned `routes` list for the browser passes below.
 
 7. **Verify browser binaries** — before starting any browser session:
-   - Check each engine in `{{ui_review_config}}.browsers` against `PLAYWRIGHT_BROWSERS_PATH`.
+   - Export `PLAYWRIGHT_BROWSERS_PATH` first if you have not already (see "Playwright cache"), then check each engine in `{{ui_review_config}}.browsers` against `$PLAYWRIGHT_BROWSERS_PATH`.
    - Collect all missing engines.
    - If any engine is missing, call `buildBrowserEscalationFinding(engine, process.platform)` for each, teardown the worktree (step 13), and return `verdict: "escalate"` with those findings.
 
@@ -118,7 +183,7 @@ Do not attempt to launch a missing engine — fail fast with `verdict: "escalate
 
    b. **Visual-diff pass (when `visualDiff.enabled` is true):**
 
-      **Visual diffing is ONLY `compareVisual` (pixelmatch). There is no ImageMagick.** Never shell out to `convert`, `compare`, `magick`, or any external image tool to diff or convert images — they are not installed and not a dependency. Screenshot via Playwright (`page.screenshot`) → pass the buffer to `compareVisual` (`lib/visual-diff.ts`). If `compareVisual` is hard to invoke, your driver script failed to resolve — fix the script (see the placement rule), do **not** substitute an external tool.
+      **Visual diffing is ONLY `compareVisual` (pixelmatch). There is no ImageMagick.** Never shell out to `convert`, `compare`, `magick`, or any external image tool to diff or convert images — they are not installed and not a dependency. Screenshot via Playwright (`page.screenshot`) → pass the buffer to `compareVisual` (`lib/visual-diff.ts`). If `compareVisual` is hard to invoke, your driver failed to import it — fix the import anchor (see "Resolving your dependencies"), do **not** substitute an external tool.
 
       For each route in the (capped) route list × each viewport in `{{ui_review_config}}.viewports`:
       - Set Playwright viewport to `{ width, height }` from the config.
@@ -147,10 +212,10 @@ Do not attempt to launch a missing engine — fail fast with `verdict: "escalate
       - Set Playwright viewport to `{ width, height }`.
       - For each route in the (capped) route list:
         - Navigate.
-        - Inject and run axe-core:
+        - Inject and run axe-core. `axe` is the plugin-root-anchored `require('axe-core')` from "Resolving your dependencies"; axe runs **inside the page**, so inject its source and evaluate there:
           ```javascript
-          import axe from 'axe-core';
-          const results = await axe.run(document);
+          await page.addScriptTag({ content: axe.source });
+          const results = await page.evaluate(async () => await window.axe.run(document));
           ```
         - Collect each violation as a raw tuple: `{ viewport, ruleId, target, impact, message, helpUrl }` (from `axe.run` output).
 
@@ -172,11 +237,13 @@ Do not attempt to launch a missing engine — fail fast with `verdict: "escalate
 12. **Write ui-review state sidecar** — after all browser passes complete and before teardown, determine whether any `compareVisual` call returned `new-baseline` or `dimension-mismatch` across all routes, viewports, and browsers in this run.
 
     - If **yes**: write `{{repo_root}}/.cloverleaf/runs/{{taskId}}/ui-review/state.json` containing:
+      <!-- cloverleaf-schema: none -->
       ```json
       {"baselines_pending": true}
       ```
       (Create intermediate directories as needed.)
     - If **no**: write `{{repo_root}}/.cloverleaf/runs/{{taskId}}/ui-review/state.json` containing:
+      <!-- cloverleaf-schema: none -->
       ```json
       {"baselines_pending": false}
       ```
@@ -186,10 +253,15 @@ Do not attempt to launch a missing engine — fail fast with `verdict: "escalate
 13. Teardown:
     ```bash
     kill $SERVER_PID 2>/dev/null || true
+    rm -f "$DRIVER"
     cd {{repo_root}}
     git worktree remove --force "$WT"
     ```
 
+    Kill the server by the PID you captured in step 3, never by command-line pattern. `pkill -f "astro dev"` also matches the command line of the shell running it, so the shell kills itself: exit 144, and every command after it in the same compound statement — the `rm -f` and `git worktree remove` above — silently never runs.
+
+    Delete every driver script you wrote, wherever you put it. `git worktree remove --force` only clears what lives inside `$WT`; a driver written anywhere else survives the run and leaks into the next one.
+
 ## Tool constraints
 
 - Read-only for source files and tests.

package/skills/cloverleaf-approve-baselines/SKILL.md

@@ -1,21 +1,23 @@
 ---
 name: cloverleaf-approve-baselines
-description: Human baseline-approval gate for the Cloverleaf UI Review pipeline. When the UI Reviewer captures new or resized visual baselines it sets baselines_pending=true in .cloverleaf/runs/{taskId}/ui-review/state.json and blocks the ui-review → qa transition. Run this skill after inspecting the new baseline images to approve them and allow the task to advance to qa. Usage — /cloverleaf-approve-baselines <TASK-ID>.
+description: Human baseline-approval gate for the Cloverleaf delivery council. When the UI member captures new or resized visual baselines it sets baselines_pending=true in .cloverleaf/runs/{taskId}/ui-review/state.json, and the council runner holds the council pass until the baselines are approved. This skill is clear-only — it presents the new baseline images, records human approval, and clears baselines_pending (it drives no FSM transition). Re-run /cloverleaf-run <TASK-ID> afterwards so the delivery council can pass. Usage — /cloverleaf-approve-baselines <TASK-ID>.
 ---
 
 # Cloverleaf — approve-baselines
 
 ## Trigger condition
 
-This skill is invoked **only** when the `cloverleaf-ui-review` skill reports that `baselines_pending` is `true` — i.e., the UI Reviewer captured at least one `new-baseline` or `dimension-mismatch` result during its run, meaning one or more baseline PNGs under `.cloverleaf/baselines/{browser}/` were created or replaced.
+This skill is invoked **only** when the delivery council's `ui` member reports that `baselines_pending` is `true` — i.e., the UI Reviewer captured at least one `new-baseline` or `dimension-mismatch` result during its run, meaning one or more baseline PNGs under `.cloverleaf/baselines/{browser}/` were created or replaced. The council runner (`/cloverleaf-run` §4.1) holds the council `pass` (which would advance `council → final-gate`) until `baselines_pending` is cleared.
 
-Do not run this skill if the task is not in `ui-review` status or if `state.json` already has `baselines_pending: false`.
+Do not run this skill if `state.json` already has `baselines_pending: false` (there is nothing to approve).
 
 ## Effect
 
-1. Writes `baselines_pending: false` to `.cloverleaf/runs/{taskId}/ui-review/state.json`.
-2. Advances the task from `ui-review` → `qa` via the normal agent transition.
-3. Commits the updated state and status to the feature branch.
+1. Presents the new baseline images and records human approval.
+2. Writes `baselines_pending: false` to `.cloverleaf/runs/{taskId}/ui-review/state.json`.
+3. Commits the updated state to the feature branch.
+
+This skill is **clear-only**: it drives **no** FSM transition. Once `baselines_pending` is `false`, re-running `/cloverleaf-run <TASK-ID>` re-dispatches the delivery council; the `ui` member now passes and the council `pass` applies (`council → final-gate`).
 
 ---
 
@@ -33,19 +35,14 @@ Do not run this skill if the task is not in `ui-review` status or if `state.json
 
 1. Capture the TASK-ID argument.
 
-2. Load the task and verify status:
+2. Load the task (context only) and read the ui-review state to confirm there is something to approve:
    ```bash
    cloverleaf-cli load-task <repo_root> <TASK-ID>
-   ```
-   Verify `status === "ui-review"`. If not, report and stop.
-
-3. Read the current ui-review state:
-   ```bash
    cloverleaf-cli read-ui-review-state <repo_root> <TASK-ID>
    ```
-   If `baselines_pending` is already `false` (or the file is absent), report that no approval is needed and stop.
+   Verify `baselines_pending === true`. If it is already `false` (or the state file is absent), report that no approval is needed and stop. (This skill gates on the `baselines_pending` flag, **not** on task `status` — under the collapsed council FSM the task sits at `council` while the UI member's baselines await approval.)
 
-4. Present the new baseline images to the human for review. The baselines live at:
+3. Present the new baseline images to the human for review. The baselines live at:
    ```
    <repo_root>/.cloverleaf/baselines/{browser}/{slug}-{viewport}.png
    ```
@@ -55,25 +52,20 @@ Do not run this skill if the task is not in `ui-review` status or if `state.json
    ```
    Display the list. Ask the human to confirm they have reviewed the images and approve the baselines before proceeding.
 
-5. Once approved, write `baselines_pending: false`:
+4. Once approved, clear the flag — write `baselines_pending: false`:
    ```bash
    cloverleaf-cli write-ui-review-state <repo_root> <TASK-ID> false
    ```
 
-6. Advance the task to qa:
-   ```bash
-   cloverleaf-cli advance-status <repo_root> <TASK-ID> qa agent '' full_pipeline
-   ```
-
-7. Commit the changes to the feature branch:
+5. Commit the changes to the feature branch:
    ```bash
    cd <repo_root>
    git add .cloverleaf/
-   git commit -m "cloverleaf: <TASK-ID> baselines approved → qa"
+   git commit -m "cloverleaf: <TASK-ID> baselines approved (baselines_pending cleared)"
    ```
 
-8. Report:
-   > "✓ Baselines approved. `baselines_pending` cleared. State → qa. Next: `/cloverleaf-qa <TASK-ID>`."
+6. Report:
+   > "✓ Baselines approved (baselines_pending cleared). Re-run `/cloverleaf-run <TASK-ID>` so the delivery council can now pass."
 
 ---
 
@@ -81,5 +73,5 @@ Do not run this skill if the task is not in `ui-review` status or if `state.json
 
 - Never push.
 - Do not modify source code or test files.
-- Do not skip step 4 — the human must acknowledge the baseline images before approval is recorded.
-- On illegal state transition, report and stop without partial commits.
+- This skill is **clear-only** — it drives **no** FSM transition (no `advance-status`). It only clears the `baselines_pending` flag; the council runner re-runs the council once the flag is `false`.
+- Do not skip step 3 — the human must acknowledge the baseline images before approval is recorded.