@cloverleaf/reference-impl 0.6.0 → 0.6.1

package/README.md

@@ -146,7 +146,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/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.1",
   "description": "Reference implementation of the Cloverleaf methodology as Claude Code skills. Implements the Tight Loop (Implementer + Reviewer).",
   "type": "module",
   "license": "MIT",

package/prompts/qa.md

@@ -24,10 +24,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

@@ -45,7 +45,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 +54,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

@@ -17,10 +17,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 +71,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 +115,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 +176,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.

package/dist/state.mjs

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