@cloverleaf/reference-impl 0.5.5 → 0.6.1

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "cloverleaf",
   "description": "Cloverleaf reference implementation — Claude Code skills for task scaffolding and the Delivery pipeline (implementer, documenter, reviewer, UI reviewer with multi-viewport visual diff, QA, merge).",
-  "version": "0.5.5",
+  "version": "0.6.0",
   "author": {
     "name": "Renato D'Arrigo",
     "email": "renato.darrigo@gmail.com"

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/VERSION

@@ -1 +1 @@
-0.5.5
+0.6.0

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>
@@ -29,8 +30,13 @@
  *   next-work-item-id <repoRoot> <project>
  *   discovery-config --repo-root <repoRoot>
  *   prep-worktree <mainRoot> <worktreePath>
+ *   dag-ready-tasks <repoRoot> <planId> <maxConcurrent>
+ *   dag-detect-cycle <repoRoot> <planId>
+ *   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';
@@ -49,6 +55,9 @@ 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) {
     process.stderr.write(msg + '\n');
     process.exit(code);
@@ -68,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' +
@@ -81,7 +91,11 @@ function usage(msg) {
         '  materialise-tasks <repoRoot> <planId>\n' +
         '  next-work-item-id <repoRoot> <project>\n' +
         '  discovery-config --repo-root <repoRoot>\n' +
-        '  prep-worktree <mainRoot> <worktreePath>\n');
+        '  prep-worktree <mainRoot> <worktreePath>\n' +
+        '  dag-ready-tasks <repoRoot> <planId> <maxConcurrent>\n' +
+        '  dag-detect-cycle <repoRoot> <planId>\n' +
+        '  walk-state-read <repoRoot> <planId>\n' +
+        '  walk-state-write <repoRoot> <walkStateJsonPath>\n');
     process.exit(2);
 }
 const [, , command, ...rest] = process.argv;
@@ -290,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);
@@ -399,6 +432,59 @@ try {
             prepWorktree(mainRoot, worktreePath);
             break;
         }
+        case 'dag-ready-tasks': {
+            const [repoRoot, planId, maxConcurrentStr] = rest;
+            if (!repoRoot || !planId || !maxConcurrentStr)
+                usage('dag-ready-tasks requires <repoRoot> <planId> <maxConcurrent>');
+            const maxConcurrent = parseInt(maxConcurrentStr, 10);
+            if (Number.isNaN(maxConcurrent) || maxConcurrent < 1)
+                die(`maxConcurrent must be a positive integer, got ${maxConcurrentStr}`);
+            const plan = loadPlan(repoRoot, planId);
+            const state = readWalkState(repoRoot, planId) ?? {
+                plan_id: planId,
+                started: new Date().toISOString(),
+                max_concurrent: maxConcurrent,
+                tasks: {},
+            };
+            const ready = computeReadyTasks(plan, state, maxConcurrent);
+            if (ready.length > 0)
+                process.stdout.write(ready.join('\n') + '\n');
+            break;
+        }
+        case 'dag-detect-cycle': {
+            const [repoRoot, planId] = rest;
+            if (!repoRoot || !planId)
+                usage('dag-detect-cycle requires <repoRoot> <planId>');
+            const plan = loadPlan(repoRoot, planId);
+            const cycle = detectCycle(plan);
+            if (cycle) {
+                process.stdout.write(cycle.cycle.join(' → ') + '\n');
+                process.exit(1);
+            }
+            break;
+        }
+        case 'walk-state-read': {
+            const [repoRoot, planId] = rest;
+            if (!repoRoot || !planId)
+                usage('walk-state-read requires <repoRoot> <planId>');
+            const state = readWalkState(repoRoot, planId);
+            if (state === null) {
+                die(`walk-state not found for plan ${planId} at ${walkStatePath(repoRoot, planId)}`, 2);
+            }
+            process.stdout.write(JSON.stringify(state, null, 2) + '\n');
+            break;
+        }
+        case 'walk-state-write': {
+            const [repoRoot, walkStateJsonPath] = rest;
+            if (!repoRoot || !walkStateJsonPath)
+                usage('walk-state-write requires <repoRoot> <walkStateJsonPath>');
+            const raw = readFileSync(walkStateJsonPath, 'utf-8');
+            const state = JSON.parse(raw);
+            if (!state.plan_id || typeof state.plan_id !== 'string')
+                die('walk-state JSON must include plan_id (string)');
+            writeWalkState(repoRoot, state);
+            break;
+        }
         default:
             usage(`Unknown command: ${command}`);
     }

package/dist/dag-walker.mjs

@@ -0,0 +1,93 @@
+/**
+ * Scheduler for the DAG walker. Given a Plan and the current walk state, returns the
+ * task IDs that are safe to spawn a Session B for right now:
+ *
+ *   1. Status is effectively `pending` (no state recorded, or recorded as `pending`).
+ *   2. Every ancestor in the task_dag has recorded state === 'merged'.
+ *   3. The count of returned IDs is capped at `maxConcurrent - currentlyRunning`.
+ *
+ * Order is deterministic (sorted ascending by task id) so callers can be reproducible.
+ */
+export function computeReadyTasks(plan, walkState, maxConcurrent) {
+    const running = Object.values(walkState.tasks).filter((t) => t.state === 'running' || t.state === 'awaiting_final_gate').length;
+    const slots = Math.max(0, maxConcurrent - running);
+    if (slots === 0)
+        return [];
+    const parents = {};
+    for (const node of plan.task_dag.nodes) {
+        parents[node.id] = [];
+    }
+    for (const edge of plan.task_dag.edges) {
+        const to = edge.to.id;
+        const from = edge.from.id;
+        if (!parents[to])
+            parents[to] = [];
+        parents[to].push(from);
+    }
+    const ready = [];
+    const allIds = plan.task_dag.nodes.map((n) => n.id).sort();
+    for (const id of allIds) {
+        const current = walkState.tasks[id];
+        const isPending = !current || current.state === 'pending';
+        if (!isPending)
+            continue;
+        const ancestorsMerged = (parents[id] ?? []).every((p) => walkState.tasks[p]?.state === 'merged');
+        if (!ancestorsMerged)
+            continue;
+        ready.push(id);
+        if (ready.length >= slots)
+            break;
+    }
+    return ready;
+}
+/**
+ * Returns `null` if the Plan's task_dag is acyclic. If a cycle is present, returns
+ * `{ cycle: string[] }` naming the task IDs involved in one cycle (order is the
+ * traversal order, which is a valid witness of the cycle).
+ *
+ * Uses Tarjan-style DFS with a white/grey/black colouring.
+ */
+export function detectCycle(plan) {
+    const adj = {};
+    for (const node of plan.task_dag.nodes)
+        adj[node.id] = [];
+    for (const edge of plan.task_dag.edges) {
+        const from = edge.from.id;
+        if (!adj[from])
+            adj[from] = [];
+        adj[from].push(edge.to.id);
+    }
+    const WHITE = 0;
+    const GREY = 1;
+    const BLACK = 2;
+    const color = {};
+    for (const id of Object.keys(adj))
+        color[id] = WHITE;
+    const path = [];
+    function dfs(id) {
+        color[id] = GREY;
+        path.push(id);
+        for (const next of adj[id] ?? []) {
+            if (color[next] === GREY) {
+                const start = path.indexOf(next);
+                return path.slice(start);
+            }
+            if (color[next] === WHITE) {
+                const cycle = dfs(next);
+                if (cycle)
+                    return cycle;
+            }
+        }
+        color[id] = BLACK;
+        path.pop();
+        return null;
+    }
+    for (const id of Object.keys(adj)) {
+        if (color[id] === WHITE) {
+            const cycle = dfs(id);
+            if (cycle)
+                return { cycle };
+        }
+    }
+    return null;
+}

package/dist/events.mjs

@@ -18,16 +18,20 @@ export function formatReason(opts) {
 }
 /**
  * Emits a status-transition event to `.cloverleaf/events/`.
- * File name: `<PROJECT>-<NNN>-status.json` where NNN is the next per-project
+ * File name: `<workItemId>-<NNN>-status.json` where NNN is the next per-work-item
  * sequential number derived from existing event files.
  *
+ * The filename scopes the counter to a single work item (v0.6 change), so
+ * parallel Delivery sessions on sibling tasks produce non-colliding event
+ * filenames that merge cleanly.
+ *
  * Returns the absolute path of the written file.
  */
 export function emitStatusTransition(repoRoot, params) {
     const { project, workItemType, workItemId, from, to, actor } = params;
-    const seq = nextEventId(repoRoot, project);
+    const seq = nextEventId(repoRoot, workItemId);
     const seqStr = String(seq).padStart(3, '0');
-    const filename = `${project}-${seqStr}-status.json`;
+    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 });
@@ -51,15 +55,16 @@ export function emitStatusTransition(repoRoot, params) {
 }
 /**
  * Emits a gate-decision event to `.cloverleaf/events/`.
- * File name: `<PROJECT>-<NNN>-gate.json`.
+ * File name: `<workItemId>-<NNN>-gate.json`. Counter is scoped to the work item
+ * (v0.6 change — see `emitStatusTransition` for rationale).
  *
  * Returns the absolute path of the written file.
  */
 export function emitGateDecision(repoRoot, params) {
     const { project, workItemId, gate, decision, actor, reasoning } = params;
-    const seq = nextEventId(repoRoot, project);
+    const seq = nextEventId(repoRoot, workItemId);
     const seqStr = String(seq).padStart(3, '0');
-    const filename = `${project}-${seqStr}-gate.json`;
+    const filename = `${workItemId}-${seqStr}-gate.json`;
     const filePath = join(eventsDir(repoRoot), filename);
     const doc = {
         event_id: randomUUID(),

package/dist/ids.mjs

@@ -12,11 +12,17 @@ export function nextTaskId(repoRoot, project) {
     const next = nums.length === 0 ? 1 : Math.max(...nums) + 1;
     return `${project}-${String(next).padStart(3, '0')}`;
 }
-export function nextEventId(repoRoot, project) {
+export function nextEventId(repoRoot, workItemId) {
     const dir = eventsDir(repoRoot);
     if (!existsSync(dir))
         return 1;
-    const re = new RegExp(`^${escapeRegex(project)}-(\\d+)-(status|gate)\\.json$`);
+    // Per-work-item sequence. Filenames are `<workItemId>-<NNN>-<status|gate>.json`,
+    // which keeps counters scoped to a single task / RFC / Spike / Plan — this matters
+    // for the v0.6 DAG walker's parallel mode, where multiple worktrees emit events
+    // 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.
+    const re = new RegExp(`^${escapeRegex(workItemId)}-(\\d+)-(status|gate)\\.json$`);
     const nums = readdirSync(dir)
         .map((f) => f.match(re))
         .filter((m) => !!m)

package/dist/index.mjs

@@ -5,3 +5,5 @@ export * from './events.mjs';
 export * from './feedback.mjs';
 export * from './validate.mjs';
 export * from './ui-review-state.mjs';
+export * from './dag-walker.mjs';
+export * from './walk-state.mjs';

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/dist/walk-state.mjs

@@ -0,0 +1,31 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { dirname, join } from 'node:path';
+export function walkStatePath(repoRoot, planId) {
+    return join(repoRoot, '.cloverleaf', 'runs', 'plan', planId, 'walk-state.json');
+}
+export function readWalkState(repoRoot, planId) {
+    const path = walkStatePath(repoRoot, planId);
+    if (!existsSync(path))
+        return null;
+    const raw = readFileSync(path, 'utf-8');
+    return JSON.parse(raw);
+}
+export function writeWalkState(repoRoot, state) {
+    const path = walkStatePath(repoRoot, state.plan_id);
+    const dir = dirname(path);
+    mkdirSync(dir, { recursive: true });
+    const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
+    writeFileSync(tmp, JSON.stringify(state, null, 2) + '\n');
+    try {
+        renameSync(tmp, path);
+    }
+    catch (err) {
+        try {
+            unlinkSync(tmp);
+        }
+        catch {
+            // best effort
+        }
+        throw err;
+    }
+}

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>
@@ -29,9 +30,14 @@
  *   next-work-item-id <repoRoot> <project>
  *   discovery-config --repo-root <repoRoot>
  *   prep-worktree <mainRoot> <worktreePath>
+ *   dag-ready-tasks <repoRoot> <planId> <maxConcurrent>
+ *   dag-detect-cycle <repoRoot> <planId>
+ *   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.js';
 import { advanceStatus } from './task.js';
@@ -51,6 +57,9 @@ 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';
 
 function die(msg: string, code = 1): never {
   process.stderr.write(msg + '\n');
@@ -72,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' +
@@ -85,7 +95,11 @@ function usage(msg?: string): never {
       '  materialise-tasks <repoRoot> <planId>\n' +
       '  next-work-item-id <repoRoot> <project>\n' +
       '  discovery-config --repo-root <repoRoot>\n' +
-      '  prep-worktree <mainRoot> <worktreePath>\n'
+      '  prep-worktree <mainRoot> <worktreePath>\n' +
+      '  dag-ready-tasks <repoRoot> <planId> <maxConcurrent>\n' +
+      '  dag-detect-cycle <repoRoot> <planId>\n' +
+      '  walk-state-read <repoRoot> <planId>\n' +
+      '  walk-state-write <repoRoot> <walkStateJsonPath>\n'
   );
   process.exit(2);
 }
@@ -300,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);
@@ -407,6 +445,60 @@ try {
       break;
     }
 
+    case 'dag-ready-tasks': {
+      const [repoRoot, planId, maxConcurrentStr] = rest;
+      if (!repoRoot || !planId || !maxConcurrentStr)
+        usage('dag-ready-tasks requires <repoRoot> <planId> <maxConcurrent>');
+      const maxConcurrent = parseInt(maxConcurrentStr, 10);
+      if (Number.isNaN(maxConcurrent) || maxConcurrent < 1)
+        die(`maxConcurrent must be a positive integer, got ${maxConcurrentStr}`);
+      const plan = loadPlan(repoRoot, planId);
+      const state = readWalkState(repoRoot, planId) ?? {
+        plan_id: planId,
+        started: new Date().toISOString(),
+        max_concurrent: maxConcurrent,
+        tasks: {},
+      };
+      const ready = computeReadyTasks(plan, state, maxConcurrent);
+      if (ready.length > 0) process.stdout.write(ready.join('\n') + '\n');
+      break;
+    }
+
+    case 'dag-detect-cycle': {
+      const [repoRoot, planId] = rest;
+      if (!repoRoot || !planId) usage('dag-detect-cycle requires <repoRoot> <planId>');
+      const plan = loadPlan(repoRoot, planId);
+      const cycle = detectCycle(plan);
+      if (cycle) {
+        process.stdout.write(cycle.cycle.join(' → ') + '\n');
+        process.exit(1);
+      }
+      break;
+    }
+
+    case 'walk-state-read': {
+      const [repoRoot, planId] = rest;
+      if (!repoRoot || !planId) usage('walk-state-read requires <repoRoot> <planId>');
+      const state = readWalkState(repoRoot, planId);
+      if (state === null) {
+        die(`walk-state not found for plan ${planId} at ${walkStatePath(repoRoot, planId)}`, 2);
+      }
+      process.stdout.write(JSON.stringify(state, null, 2) + '\n');
+      break;
+    }
+
+    case 'walk-state-write': {
+      const [repoRoot, walkStateJsonPath] = rest;
+      if (!repoRoot || !walkStateJsonPath)
+        usage('walk-state-write requires <repoRoot> <walkStateJsonPath>');
+      const raw = readFileSync(walkStateJsonPath, 'utf-8');
+      const state = JSON.parse(raw);
+      if (!state.plan_id || typeof state.plan_id !== 'string')
+        die('walk-state JSON must include plan_id (string)');
+      writeWalkState(repoRoot, state);
+      break;
+    }
+
     default:
       usage(`Unknown command: ${command}`);
   }