@cloverleaf/reference-impl 0.6.0 → 0.6.2

package/README.md

@@ -96,10 +96,16 @@ The installer (`install.sh`) automatically runs the Playwright browser install s
 
     npx playwright install chromium webkit firefox
 
-On **Linux**, webkit additionally requires system-level dependencies:
+On **Linux**, webkit additionally requires system-level dependencies. By default `install.sh` installs webkit deps only:
 
     npx playwright install-deps webkit
 
+To also install firefox system deps (enabling the full chromium + webkit + firefox browser matrix for the UI Reviewer), pass `--with-cross-browser` to the installer:
+
+    ./install.sh --with-cross-browser
+
+This runs `npx playwright install-deps webkit firefox` instead. When the flag is omitted, `install.sh` prints a note reminding you how to enable cross-browser support later.
+
 **Disk footprint:** approximately 600–650 MB total across all three browsers in the default `PLAYWRIGHT_BROWSERS_PATH` location (`~/.cache/ms-playwright/`).
 
 | Browser   | Approx. size |
@@ -146,7 +152,7 @@ The Reviewer never switches branches. It reads files via `git show` and runs tes
 
 ## Package layout
 
-- `lib/` — TypeScript library used by the CLI. State, events, feedback, IDs, paths. Includes `buildBaselinePath(repoRoot, browser, slug, viewport)` (`lib/visual-diff.ts`) for constructing canonical baseline paths under `.cloverleaf/baselines/{browser}/`. `lib/ui-browser.ts` exports `buildBrowserEscalationFinding` and `applyMaxCombinationsCap` (used by the UI Reviewer prompt for per-engine escalation and combination-count capping). `lib/ui-review-state.ts` exports `readUiReviewState`, `writeUiReviewState`, and `uiReviewStatePath` — the baseline-approval sidecar API for `.cloverleaf/runs/{taskId}/ui-review/state.json`.
+- `lib/` — TypeScript library used by the CLI. State, events, feedback, IDs, paths. Includes `buildBaselinePath(repoRoot, browser, slug, viewport)` (`lib/visual-diff.ts`) for constructing canonical baseline paths under `.cloverleaf/baselines/{browser}/`. `lib/ui-browser.ts` exports `buildBrowserEscalationFinding` and `applyMaxCombinationsCap` (used by the UI Reviewer prompt for per-engine escalation and combination-count capping). `lib/ui-review-state.ts` exports `readUiReviewState`, `writeUiReviewState`, and `uiReviewStatePath` — the baseline-approval sidecar API for `.cloverleaf/runs/{taskId}/ui-review/state.json`. The CLI exposes `write-baseline <repoRoot> <taskId> <browser> <slug> <viewport> <sourceFile>` as the safe write path for baselines; it enforces the `baselines_pending` guard and uses `buildBaselinePath` internally.
 - `skills/` — Claude Code skill markdown files.
 - `prompts/` — Implementer/Reviewer subagent system prompts.
 - `examples/toy-repo/` — standalone demo repo.

package/dist/cli.mjs

@@ -15,6 +15,7 @@
  *   ui-review-config --repo-root <repoRoot>
  *   read-ui-review-state <repoRoot> <taskId>
  *   write-ui-review-state <repoRoot> <taskId> <baselines_pending>
+ *   write-baseline <repoRoot> <taskId> <browser> <slug> <viewport> <sourceFile>
  *   plugin-root
  *   load-rfc <repoRoot> <id>
  *   save-rfc <repoRoot> <filePath>
@@ -34,7 +35,8 @@
  *   walk-state-read <repoRoot> <planId>
  *   walk-state-write <repoRoot> <walkStateJsonPath>
  */
-import { readFileSync } from 'node:fs';
+import { readFileSync, mkdirSync, copyFileSync } from 'node:fs';
+import { dirname } from 'node:path';
 import { execSync } from 'node:child_process';
 import { loadTask } from './task.mjs';
 import { advanceStatus } from './task.mjs';
@@ -53,6 +55,7 @@ import { loadPlan, savePlan, advancePlanStatus, materialiseTasksFromPlan } from
 import { loadDiscoveryConfig } from './discovery-config.mjs';
 import { prepWorktree } from './prep-worktree.mjs';
 import { readUiReviewState, writeUiReviewState } from './ui-review-state.mjs';
+import { buildBaselinePath } from './visual-diff.mjs';
 import { computeReadyTasks, detectCycle } from './dag-walker.mjs';
 import { readWalkState, writeWalkState, walkStatePath } from './walk-state.mjs';
 function die(msg, code = 1) {
@@ -74,6 +77,7 @@ function usage(msg) {
         '  ui-review-config --repo-root <repoRoot>\n' +
         '  read-ui-review-state <repoRoot> <taskId>\n' +
         '  write-ui-review-state <repoRoot> <taskId> <baselines_pending>\n' +
+        '  write-baseline <repoRoot> <taskId> <browser> <slug> <viewport> <sourceFile>\n' +
         '  plugin-root\n' +
         '  load-rfc <repoRoot> <id>\n' +
         '  save-rfc <repoRoot> <filePath>\n' +
@@ -300,6 +304,25 @@ try {
             writeUiReviewState(repoRoot, taskId, { baselines_pending });
             break;
         }
+        case 'write-baseline': {
+            const [repoRoot, taskId, browser, slug, viewport, sourceFile] = rest;
+            if (!repoRoot || !taskId || !browser || !slug || !viewport || !sourceFile)
+                usage('write-baseline requires <repoRoot> <taskId> <browser> <slug> <viewport> <sourceFile>');
+            // Guard: refuse writes under .cloverleaf/baselines/ when baselines_pending is true.
+            // This prevents the UI Reviewer from bypassing the human baseline-approval gate.
+            const uiState = readUiReviewState(repoRoot, taskId);
+            if (uiState.baselines_pending) {
+                die(`write-baseline refused: baselines_pending is true for task ${taskId}.\n` +
+                    `A human must approve the pending baselines via the baseline-approval gate before new baselines can be written.\n` +
+                    `Run: cloverleaf-cli write-ui-review-state <repoRoot> ${taskId} false` +
+                    ` after the human approves the baselines.`);
+            }
+            const destPath = buildBaselinePath(repoRoot, browser, slug, viewport);
+            mkdirSync(dirname(destPath), { recursive: true });
+            copyFileSync(sourceFile, destPath);
+            process.stdout.write(destPath + '\n');
+            break;
+        }
         case 'plugin-root': {
             process.stdout.write(getPluginRoot());
             process.exit(0);

package/dist/prep-worktree.mjs

@@ -1,6 +1,6 @@
 import { cpSync, existsSync, rmSync } from 'node:fs';
 import { execSync } from 'node:child_process';
-import { join } from 'node:path';
+import { join, dirname } from 'node:path';
 /**
  * Prepare a freshly-created git worktree of the cloverleaf monorepo for running reference-impl
  * tests. Addresses the v0.5 dogfood finding (CLV-16, CLV-17 Delivery runs) where Reviewer/QA
@@ -19,10 +19,73 @@ import { join } from 'node:path';
  *   - Copy `<main>/reference-impl/node_modules` → `<wt>/reference-impl/node_modules`
  *     The `@cloverleaf/standard → ../../../standard` relative symlink is preserved verbatim so
  *     it resolves to the worktree's OWN standard/, not main's.
+ *
+ * Walker-mode resilience (CLV-37): when `mainRoot` is itself a walker worktree without
+ * node_modules, walk up ancestor directories until one is found that contains both
+ * `standard/node_modules` and `reference-impl/node_modules`. This allows the orchestrator to
+ * pass the current walker worktree path without needing to know the actual primary repo root.
  */
-export function prepWorktree(mainRoot, worktreePath) {
+/**
+ * Walk up the directory tree from `startDir` until a directory is found that contains both
+ * `standard/node_modules` and `reference-impl/node_modules`. Returns that directory, or null
+ * if the filesystem root is reached without finding one.
+ */
+function findPrimaryRoot(startDir) {
+    let candidate = startDir;
+    while (true) {
+        if (existsSync(join(candidate, 'standard', 'node_modules')) &&
+            existsSync(join(candidate, 'reference-impl', 'node_modules'))) {
+            return candidate;
+        }
+        const parent = dirname(candidate);
+        if (parent === candidate) {
+            // Reached filesystem root without finding a match.
+            return null;
+        }
+        candidate = parent;
+    }
+}
+/**
+ * Walk up from `startDir` to find the nearest ancestor where the given `subdir` exists.
+ * Returns the ancestor path, or null if the filesystem root is reached without a match.
+ */
+function findNearestAncestorWithSubdir(startDir, subdir) {
+    let candidate = startDir;
+    while (true) {
+        if (existsSync(join(candidate, subdir))) {
+            return candidate;
+        }
+        const parent = dirname(candidate);
+        if (parent === candidate) {
+            return null;
+        }
+        candidate = parent;
+    }
+}
+/**
+ * Build a diagnostic error message when `findPrimaryRoot` fails to find an ancestor with
+ * both `standard/node_modules` and `reference-impl/node_modules`. Walks up separately for
+ * each subdirectory to produce a precise message naming the specific missing directory.
+ */
+function buildMissingNodeModulesError(mainRoot) {
+    const hasStandard = findNearestAncestorWithSubdir(mainRoot, join('standard', 'node_modules'));
+    const hasRefImpl = findNearestAncestorWithSubdir(mainRoot, join('reference-impl', 'node_modules'));
+    if (hasStandard !== null && hasRefImpl === null) {
+        // standard/node_modules exists somewhere in the tree but reference-impl/node_modules does not.
+        const missing = join(hasStandard, 'reference-impl', 'node_modules');
+        return new Error(`main missing reference-impl/node_modules at ${missing} — run \`npm ci\` in main's reference-impl/ first`);
+    }
+    if (hasRefImpl !== null && hasStandard === null) {
+        // reference-impl/node_modules exists somewhere in the tree but standard/node_modules does not.
+        const missing = join(hasRefImpl, 'standard', 'node_modules');
+        return new Error(`main missing standard/node_modules at ${missing} — run \`npm ci\` in main's standard/ first`);
+    }
+    // Neither found (or both missing): fall back to reporting standard/node_modules against the
+    // original mainRoot argument (preserves prior behaviour for the truly-empty case).
     const mainStandardNm = join(mainRoot, 'standard', 'node_modules');
-    const mainRefImplNm = join(mainRoot, 'reference-impl', 'node_modules');
+    return new Error(`main missing standard/node_modules at ${mainStandardNm} — run \`npm ci\` in main's standard/ first`);
+}
+export function prepWorktree(mainRoot, worktreePath) {
     const wtStandardPkg = join(worktreePath, 'standard', 'package.json');
     const wtRefImplPkg = join(worktreePath, 'reference-impl', 'package.json');
     if (!existsSync(wtStandardPkg)) {
@@ -31,12 +94,14 @@ export function prepWorktree(mainRoot, worktreePath) {
     if (!existsSync(wtRefImplPkg)) {
         throw new Error(`worktree missing reference-impl/package.json at ${wtRefImplPkg}`);
     }
-    if (!existsSync(mainStandardNm)) {
-        throw new Error(`main missing standard/node_modules at ${mainStandardNm} — run \`npm ci\` in main's standard/ first`);
-    }
-    if (!existsSync(mainRefImplNm)) {
-        throw new Error(`main missing reference-impl/node_modules at ${mainRefImplNm} — run \`npm ci\` in main's reference-impl/ first`);
+    // Resolve the actual primary repo root: start from mainRoot and walk up until we find a
+    // directory containing both standard/node_modules and reference-impl/node_modules.
+    const resolvedMain = findPrimaryRoot(mainRoot);
+    if (resolvedMain === null) {
+        throw buildMissingNodeModulesError(mainRoot);
     }
+    const mainStandardNm = join(resolvedMain, 'standard', 'node_modules');
+    const mainRefImplNm = join(resolvedMain, 'reference-impl', 'node_modules');
     const wtStandardNm = join(worktreePath, 'standard', 'node_modules');
     const wtRefImplNm = join(worktreePath, 'reference-impl', 'node_modules');
     // verbatimSymlinks keeps relative symlink targets byte-identical, so the @cloverleaf/standard

package/install.sh

@@ -7,10 +7,23 @@ set -euo pipefail
 # `claude plugin` CLI. Point Claude Code at the cloverleaf repo root (where
 # .claude-plugin/marketplace.json lives), then install the plugin from the
 # resulting marketplace.
+#
+# Flags:
+#   --with-cross-browser   On Linux, also install firefox system deps (in
+#                          addition to webkit) so the UI Reviewer can run the
+#                          full chromium + webkit + firefox browser matrix.
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 REPO_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
 
+# Parse flags from "$@".
+WITH_CROSS_BROWSER=0
+for arg in "$@"; do
+  case "$arg" in
+    --with-cross-browser) WITH_CROSS_BROWSER=1 ;;
+  esac
+done
+
 if ! command -v claude >/dev/null 2>&1; then
   echo "error: 'claude' CLI not found on PATH."
   echo "Install Claude Code first: https://docs.claude.com/claude-code"
@@ -50,11 +63,19 @@ echo ""
 
 npx playwright install chromium webkit firefox
 
-# On Linux, system deps for webkit are also required.
+# On Linux, system deps are also required.
 if [ "$(uname -s)" = "Linux" ]; then
   echo ""
-  echo "Linux detected — installing webkit system dependencies..."
-  npx playwright install-deps webkit
+  if [ "$WITH_CROSS_BROWSER" = "1" ]; then
+    echo "Linux detected — installing webkit + firefox system dependencies (--with-cross-browser)..."
+    npx playwright install-deps webkit firefox
+  else
+    echo "Linux detected — installing webkit system dependencies..."
+    npx playwright install-deps webkit
+    echo ""
+    echo "Note: to also install firefox system dependencies for full cross-browser"
+    echo "  UI review support, re-run with: ./install.sh --with-cross-browser"
+  fi
 fi
 
 echo ""

package/lib/cli.ts

@@ -15,6 +15,7 @@
  *   ui-review-config --repo-root <repoRoot>
  *   read-ui-review-state <repoRoot> <taskId>
  *   write-ui-review-state <repoRoot> <taskId> <baselines_pending>
+ *   write-baseline <repoRoot> <taskId> <browser> <slug> <viewport> <sourceFile>
  *   plugin-root
  *   load-rfc <repoRoot> <id>
  *   save-rfc <repoRoot> <filePath>
@@ -35,7 +36,8 @@
  *   walk-state-write <repoRoot> <walkStateJsonPath>
  */
 
-import { readFileSync } from 'node:fs';
+import { readFileSync, mkdirSync, copyFileSync } from 'node:fs';
+import { dirname } from 'node:path';
 import { execSync } from 'node:child_process';
 import { loadTask } from './task.js';
 import { advanceStatus } from './task.js';
@@ -55,6 +57,7 @@ import { loadPlan, savePlan, advancePlanStatus, materialiseTasksFromPlan, type P
 import { loadDiscoveryConfig } from './discovery-config.js';
 import { prepWorktree } from './prep-worktree.js';
 import { readUiReviewState, writeUiReviewState } from './ui-review-state.js';
+import { buildBaselinePath } from './visual-diff.js';
 import { computeReadyTasks, detectCycle } from './dag-walker.js';
 import { readWalkState, writeWalkState, walkStatePath } from './walk-state.js';
 
@@ -78,6 +81,7 @@ function usage(msg?: string): never {
       '  ui-review-config --repo-root <repoRoot>\n' +
       '  read-ui-review-state <repoRoot> <taskId>\n' +
       '  write-ui-review-state <repoRoot> <taskId> <baselines_pending>\n' +
+      '  write-baseline <repoRoot> <taskId> <browser> <slug> <viewport> <sourceFile>\n' +
       '  plugin-root\n' +
       '  load-rfc <repoRoot> <id>\n' +
       '  save-rfc <repoRoot> <filePath>\n' +
@@ -310,6 +314,30 @@ try {
       break;
     }
 
+    case 'write-baseline': {
+      const [repoRoot, taskId, browser, slug, viewport, sourceFile] = rest;
+      if (!repoRoot || !taskId || !browser || !slug || !viewport || !sourceFile)
+        usage(
+          'write-baseline requires <repoRoot> <taskId> <browser> <slug> <viewport> <sourceFile>'
+        );
+      // Guard: refuse writes under .cloverleaf/baselines/ when baselines_pending is true.
+      // This prevents the UI Reviewer from bypassing the human baseline-approval gate.
+      const uiState = readUiReviewState(repoRoot, taskId);
+      if (uiState.baselines_pending) {
+        die(
+          `write-baseline refused: baselines_pending is true for task ${taskId}.\n` +
+            `A human must approve the pending baselines via the baseline-approval gate before new baselines can be written.\n` +
+            `Run: cloverleaf-cli write-ui-review-state <repoRoot> ${taskId} false` +
+            ` after the human approves the baselines.`
+        );
+      }
+      const destPath = buildBaselinePath(repoRoot, browser, slug, viewport);
+      mkdirSync(dirname(destPath), { recursive: true });
+      copyFileSync(sourceFile, destPath);
+      process.stdout.write(destPath + '\n');
+      break;
+    }
+
     case 'plugin-root': {
       process.stdout.write(getPluginRoot());
       process.exit(0);

package/lib/prep-worktree.ts

@@ -1,6 +1,6 @@
 import { cpSync, existsSync, rmSync } from 'node:fs';
 import { execSync } from 'node:child_process';
-import { join } from 'node:path';
+import { join, dirname } from 'node:path';
 
 /**
  * Prepare a freshly-created git worktree of the cloverleaf monorepo for running reference-impl
@@ -20,10 +20,80 @@ import { join } from 'node:path';
  *   - Copy `<main>/reference-impl/node_modules` → `<wt>/reference-impl/node_modules`
  *     The `@cloverleaf/standard → ../../../standard` relative symlink is preserved verbatim so
  *     it resolves to the worktree's OWN standard/, not main's.
+ *
+ * Walker-mode resilience (CLV-37): when `mainRoot` is itself a walker worktree without
+ * node_modules, walk up ancestor directories until one is found that contains both
+ * `standard/node_modules` and `reference-impl/node_modules`. This allows the orchestrator to
+ * pass the current walker worktree path without needing to know the actual primary repo root.
  */
-export function prepWorktree(mainRoot: string, worktreePath: string): void {
+
+/**
+ * Walk up the directory tree from `startDir` until a directory is found that contains both
+ * `standard/node_modules` and `reference-impl/node_modules`. Returns that directory, or null
+ * if the filesystem root is reached without finding one.
+ */
+function findPrimaryRoot(startDir: string): string | null {
+  let candidate = startDir;
+  while (true) {
+    if (
+      existsSync(join(candidate, 'standard', 'node_modules')) &&
+      existsSync(join(candidate, 'reference-impl', 'node_modules'))
+    ) {
+      return candidate;
+    }
+    const parent = dirname(candidate);
+    if (parent === candidate) {
+      // Reached filesystem root without finding a match.
+      return null;
+    }
+    candidate = parent;
+  }
+}
+
+/**
+ * Walk up from `startDir` to find the nearest ancestor where the given `subdir` exists.
+ * Returns the ancestor path, or null if the filesystem root is reached without a match.
+ */
+function findNearestAncestorWithSubdir(startDir: string, subdir: string): string | null {
+  let candidate = startDir;
+  while (true) {
+    if (existsSync(join(candidate, subdir))) {
+      return candidate;
+    }
+    const parent = dirname(candidate);
+    if (parent === candidate) {
+      return null;
+    }
+    candidate = parent;
+  }
+}
+
+/**
+ * Build a diagnostic error message when `findPrimaryRoot` fails to find an ancestor with
+ * both `standard/node_modules` and `reference-impl/node_modules`. Walks up separately for
+ * each subdirectory to produce a precise message naming the specific missing directory.
+ */
+function buildMissingNodeModulesError(mainRoot: string): Error {
+  const hasStandard = findNearestAncestorWithSubdir(mainRoot, join('standard', 'node_modules'));
+  const hasRefImpl = findNearestAncestorWithSubdir(mainRoot, join('reference-impl', 'node_modules'));
+
+  if (hasStandard !== null && hasRefImpl === null) {
+    // standard/node_modules exists somewhere in the tree but reference-impl/node_modules does not.
+    const missing = join(hasStandard, 'reference-impl', 'node_modules');
+    return new Error(`main missing reference-impl/node_modules at ${missing} — run \`npm ci\` in main's reference-impl/ first`);
+  }
+  if (hasRefImpl !== null && hasStandard === null) {
+    // reference-impl/node_modules exists somewhere in the tree but standard/node_modules does not.
+    const missing = join(hasRefImpl, 'standard', 'node_modules');
+    return new Error(`main missing standard/node_modules at ${missing} — run \`npm ci\` in main's standard/ first`);
+  }
+  // Neither found (or both missing): fall back to reporting standard/node_modules against the
+  // original mainRoot argument (preserves prior behaviour for the truly-empty case).
   const mainStandardNm = join(mainRoot, 'standard', 'node_modules');
-  const mainRefImplNm = join(mainRoot, 'reference-impl', 'node_modules');
+  return new Error(`main missing standard/node_modules at ${mainStandardNm} — run \`npm ci\` in main's standard/ first`);
+}
+
+export function prepWorktree(mainRoot: string, worktreePath: string): void {
   const wtStandardPkg = join(worktreePath, 'standard', 'package.json');
   const wtRefImplPkg = join(worktreePath, 'reference-impl', 'package.json');
 
@@ -33,13 +103,17 @@ export function prepWorktree(mainRoot: string, worktreePath: string): void {
   if (!existsSync(wtRefImplPkg)) {
     throw new Error(`worktree missing reference-impl/package.json at ${wtRefImplPkg}`);
   }
-  if (!existsSync(mainStandardNm)) {
-    throw new Error(`main missing standard/node_modules at ${mainStandardNm} — run \`npm ci\` in main's standard/ first`);
-  }
-  if (!existsSync(mainRefImplNm)) {
-    throw new Error(`main missing reference-impl/node_modules at ${mainRefImplNm} — run \`npm ci\` in main's reference-impl/ first`);
+
+  // Resolve the actual primary repo root: start from mainRoot and walk up until we find a
+  // directory containing both standard/node_modules and reference-impl/node_modules.
+  const resolvedMain = findPrimaryRoot(mainRoot);
+  if (resolvedMain === null) {
+    throw buildMissingNodeModulesError(mainRoot);
   }
 
+  const mainStandardNm = join(resolvedMain, 'standard', 'node_modules');
+  const mainRefImplNm = join(resolvedMain, 'reference-impl', 'node_modules');
+
   const wtStandardNm = join(worktreePath, 'standard', 'node_modules');
   const wtRefImplNm = join(worktreePath, 'reference-impl', 'node_modules');
 

package/package.json

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

package/prompts/documenter.md

@@ -10,6 +10,14 @@ You are the Cloverleaf Documenter. Your job: produce doc-only commits that updat
 - **Repo root**: {{repo_root}}
 - **Diff from base**: {{diff}}
 
+## Pre-flight — ensure correct working directory
+
+```bash
+cd "$(git rev-parse --show-toplevel)"
+```
+
+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.
+
 ## Tool constraints
 
 - Use `git worktree add <temp> {{branch}}` to work on an isolated checkout. Do NOT `git checkout` in the main working directory.

package/prompts/implementer.md

@@ -11,6 +11,14 @@ You are the Cloverleaf Implementer agent. Your job: take a Task and produce work
 
 ## Your process
 
+0. **Pre-flight — ensure correct working directory.**
+
+   ```bash
+   cd "$(git rev-parse --show-toplevel)"
+   ```
+
+   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 `title`, `acceptance_criteria`, `definition_of_done`, and `context`. Read any referenced files.
 2. If `feedback` is present, re-read each finding; plan how to address them.
 3. Create a new branch named `cloverleaf/<task.id>` from `base_branch` using `git checkout -b cloverleaf/<task.id>`.

package/prompts/qa.md

@@ -17,6 +17,14 @@ The Standard's QA contract requires a `preview_uri`. You were passed the sentine
 
 ## Runtime procedure
 
+0. **Pre-flight — ensure correct working directory.**
+
+   ```bash
+   cd "$(git rev-parse --show-toplevel)"
+   ```
+
+   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. Set up isolated worktree and prepare its node_modules + standard/dist. The `prep-worktree`
    helper copies main's `standard/node_modules` and `reference-impl/node_modules` into the
    worktree and runs the standard build script so the @cloverleaf/standard symlink resolves
@@ -24,10 +32,13 @@ The Standard's QA contract requires a `preview_uri`. You were passed the sentine
    '@cloverleaf/standard/validators/index.js'` because git worktrees don't inherit node_modules.)
    ```bash
    TMPDIR=$(mktemp -d)
-   git worktree add "$TMPDIR" {{branch}}
+   SHA=$(git rev-parse {{branch}})
+   git worktree add --detach "$TMPDIR" "$SHA"
    cloverleaf-cli prep-worktree {{repo_root}} "$TMPDIR"
    ```
 
+   Use `--detach` with a SHA rather than a branch name: the calling context (e.g., the walker) may already have `{{branch}}` 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.
+
 2. Inspect the changed files (from the diff). For each QA rule whose `match` patterns match ≥1 changed file, queue its command.
 
 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:

package/prompts/reviewer.md

@@ -11,6 +11,14 @@ You are the Cloverleaf Reviewer agent. Your job: perform a fresh-eyes review of
 
 ## Your process
 
+0. **Pre-flight — ensure correct working directory.**
+
+   ```bash
+   cd "$(git rev-parse --show-toplevel)"
+   ```
+
+   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.
 3. For each acceptance criterion, determine whether the diff satisfies it. Note any unsatisfied criteria as findings.
@@ -45,7 +53,8 @@ A `pass` verdict MAY have an empty `findings` array or omit it. A `bounce` verdi
 
   ```bash
   MAIN=$(pwd)
-  git worktree add /tmp/cl-review-<task-id> cloverleaf/<task-id>
+  SHA=$(git rev-parse cloverleaf/<task-id>)
+  git worktree add --detach /tmp/cl-review-<task-id> "$SHA"
   cloverleaf-cli prep-worktree "$MAIN" /tmp/cl-review-<task-id>
   cd /tmp/cl-review-<task-id>/reference-impl
   npm test
@@ -53,6 +62,8 @@ A `pass` verdict MAY have an empty `findings` array or omit it. A `bounce` verdi
   git worktree remove /tmp/cl-review-<task-id>
   ```
 
+  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.
 - Severities (per the Cloverleaf feedback schema): `blocker` = wrong behavior / missing AC / broken tests; `error` = notable defect that should be fixed but doesn't break AC; `warning` = should fix; `info` = nit / style. Use `blocker` and `error` for bounces.
 - If a criterion is subjective, lean toward pass — the task author chose those words deliberately.

package/prompts/ui-reviewer.md

@@ -2,6 +2,14 @@
 
 You are the Cloverleaf UI Reviewer. Your job: review a task's UI changes at multiple viewports and browser engines for accessibility violations (axe-core) and visual regressions (pixelmatch) using headless Playwright browsers. You are read-only for source code and tests — but you DO write baseline/diff artifacts under `.cloverleaf/` on the feature branch.
 
+## Pre-flight — ensure correct working directory
+
+```bash
+cd "$(git rev-parse --show-toplevel)"
+```
+
+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.
+
 ## Input
 
 - **Task**: {{task}}
@@ -17,10 +25,10 @@ You are the Cloverleaf UI Reviewer. Your job: review a task's UI changes at mult
 
 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.
+- `<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.
 - `<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`.**
+**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.
 
@@ -71,19 +79,21 @@ Do not attempt to launch a missing engine — fail fast with `verdict: "escalate
 
 2. Set up an isolated worktree of the feature branch:
    ```bash
-   TMPDIR=$(mktemp -d)
-   git worktree add "$TMPDIR" {{branch}}
-   npx cloverleaf-cli prep-worktree {{repo_root}} "$TMPDIR"
+   WT=$(mktemp -d)
+   git worktree add "$WT" {{branch}}
+   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:
    ```bash
-   cd "$TMPDIR/site"
+   cd "$WT/site"
    npm ci
    npm run dev -- --port={{preview_port}} &
    SERVER_PID=$!
    ```
 
+   > **Playwright script placement (Bug #3 fix):** If you need to write a standalone `.mjs` driver script at any point, place it **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 outside the worktree (where `node_modules/playwright` was installed by `npm ci`) cannot resolve the `playwright` import and will fail.
+
 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:
@@ -113,7 +123,7 @@ Do not attempt to launch a missing engine — fail fast with `verdict: "escalate
       - 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.
+      - Note: use `{{repo_root}}` (the absolute main-repo path), NOT `$WT` or the worktree. See the "Paths" section.
       - Call `compareVisual` (from `lib/visual-diff.ts`) with:
         - `baselinePath = {{repo_root}}/.cloverleaf/baselines/{browser}/{slug}-{viewport}.png`
         - `candidateBuf = <candidate PNG>`
@@ -174,7 +184,7 @@ Do not attempt to launch a missing engine — fail fast with `verdict: "escalate
     ```bash
     kill $SERVER_PID 2>/dev/null || true
     cd {{repo_root}}
-    git worktree remove --force "$TMPDIR"
+    git worktree remove --force "$WT"
     ```
 
 ## Tool constraints

package/skills/cloverleaf-run-plan/SKILL.md

@@ -77,7 +77,8 @@ description: Autonomous DAG walker for Cloverleaf Plans. Given a PLAN-ID in stat
       Per ready task:
 
       ```bash
-      WT="/tmp/walker-<PLAN-ID>-<TASK-ID>"
+      WT="${XDG_CACHE_HOME:-$HOME/.cache}/cloverleaf/walker/<PLAN-ID>-<TASK-ID>"
+      mkdir -p "$(dirname "$WT")"
       rm -rf "$WT"  # idempotent: clean any leftover from a prior run
       git -C <repo_root> worktree add "$WT" -b cloverleaf/<TASK-ID> main
       ```
@@ -118,12 +119,24 @@ description: Autonomous DAG walker for Cloverleaf Plans. Given a PLAN-ID in stat
          ```
       2. Read the user's response.
       3. If it matches `^y(es)?$|^Y(ES)?$` → perform the merge in the primary repo:
+
+         First, **guard against conflict markers** — scan every file changed on the task branch for unresolved conflict markers before attempting the merge:
          ```bash
          cd <repo_root>
          git checkout main
-         git merge --no-ff cloverleaf/<TASK-ID> -m "cloverleaf: <TASK-ID> merged (<fast_lane | full_pipeline>)"
+         CHANGED_FILES=$(git diff --name-only main..cloverleaf/<TASK-ID>)
+         if [ -n "$CHANGED_FILES" ] && echo "$CHANGED_FILES" | xargs grep -l -E '^(<{7}|={7}|>{7})' 2>/dev/null | grep -q .; then
+           echo "ERROR: conflict markers found in changed files — aborting merge for <TASK-ID>"
+           echo "$CHANGED_FILES" | xargs grep -l -E '^(<{7}|={7}|>{7})' 2>/dev/null
+           # Do NOT proceed; mark task escalated and surface to user
+         else
+           git merge --no-ff cloverleaf/<TASK-ID> -m "cloverleaf: <TASK-ID> merged (<fast_lane | full_pipeline>)"
+         fi
          ```
-         Then advance state and commit:
+
+         If conflict markers are found, abort the merge: mark task `state: "escalated"` in walk-state, surface to the user with the list of affected files, and do NOT advance state. Continue with the next queued task.
+
+         After a **successful** `git merge --no-ff`, advance state and commit:
          ```bash
          # Fast lane:
          cloverleaf-cli emit-gate-decision <repo_root> <TASK-ID> human_merge approve human
@@ -135,7 +148,19 @@ description: Autonomous DAG walker for Cloverleaf Plans. Given a PLAN-ID in stat
          ```bash
          git add .cloverleaf/ && git commit -m "cloverleaf: <TASK-ID> merged"
          ```
-         Capture the merge commit SHA. Mark task `state: "merged"` with `merge_commit` in walk-state. Send `y` (informational) back to Session B so it can record the outcome and exit, but the walker is the authoritative merge-performer.
+         Capture the merge commit SHA:
+         ```bash
+         MERGE_COMMIT=$(git rev-parse HEAD)
+         ```
+         Immediately update walk-state to record the successful merge (bug #7 fix — walk-state must reflect `merged` state):
+         ```bash
+         # Write a temporary walk-state JSON with state: "merged" and merge_commit, then persist atomically
+         # (build the updated walk-state object in-memory and call walk-state-write)
+         cloverleaf-cli walk-state-write <repo_root> <updated-walk-state-json-path>
+         # The updated walk-state sets tasks["<TASK-ID>"].state = "merged"
+         #                           and tasks["<TASK-ID>"].merge_commit = "$MERGE_COMMIT"
+         ```
+         Send `y` (informational) back to Session B so it can record the outcome and exit, but the walker is the authoritative merge-performer.
          **Tear down the worktree**: `git -C <repo_root> worktree remove --force <worktree_path>`. Delete the branch is optional (keep if useful for post-hoc inspection).
       4. If it matches `^n(o)?$|^N(O)?$` → mark task `state: "awaiting_final_gate"`. Send `n` to Session B. **Keep the worktree** so the user can re-run `/cloverleaf-merge <TASK-ID>` manually pointing at it, or fix and retry. Continue with the next queued task.
       5. Otherwise → forward the user's text as a user turn to Session B via `mcp__claw-drive__send_turn` (it's a question). Wait for the session's next `turn_completed`. Print the answer. **Re-surface the same y/N prompt** (with the Q&A appended to shown context). Loop until step 3 or 4 fires.
@@ -159,9 +184,13 @@ The walker constructs a per-task `scenario_brief` roughly like:
 
 ```
 You are driving <TASK-ID> Delivery via /cloverleaf-run inside a dedicated
-git worktree at <worktree_path>. The worktree is checked out to branch
+git worktree rooted at $WORKTREE_ROOT. The worktree is checked out to branch
 cloverleaf/<TASK-ID> (already created from main). Task risk_class: <class>.
 
+**Pre-flight: before any task steps, run `cd "$WORKTREE_ROOT"` to ensure your
+working directory is the worktree root, not whatever directory the session
+inherited.**
+
 Plan: invoke `/cloverleaf-run <TASK-ID>`.
 
 **DO NOT invoke `/cloverleaf-merge`**. Fast lane stops after `/cloverleaf-review`