@cloverleaf/reference-impl 0.5.5 → 0.6.0

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

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

package/dist/cli.mjs

@@ -29,6 +29,10 @@
  *   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 { execSync } from 'node:child_process';
@@ -49,6 +53,8 @@ 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 { 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);
@@ -81,7 +87,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;
@@ -399,6 +409,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/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

@@ -29,6 +29,10 @@
  *   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';
@@ -51,6 +55,8 @@ 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 { 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');
@@ -85,7 +91,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);
 }
@@ -407,6 +417,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}`);
   }

package/lib/dag-walker.ts

@@ -0,0 +1,133 @@
+import type { PlanDoc } from './plan.js';
+
+export interface WalkState {
+  plan_id: string;
+  started: string;
+  max_concurrent: number;
+  tasks: Record<
+    string,
+    | { state: 'pending' }
+    | { state: 'running'; session_id: string; started_at: string; last_seq: number }
+    | {
+        state: 'awaiting_final_gate';
+        session_id: string;
+        started_at: string;
+        last_seq: number;
+      }
+    | {
+        state: 'merged';
+        session_id: string;
+        merged_at: string;
+        merge_commit: string;
+      }
+    | {
+        state: 'escalated';
+        session_id: string;
+        escalated_at: string;
+        reason: string;
+      }
+  >;
+}
+
+/**
+ * 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: PlanDoc,
+  walkState: WalkState,
+  maxConcurrent: number,
+): string[] {
+  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: Record<string, string[]> = {};
+  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: string[] = [];
+  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: PlanDoc): { cycle: string[] } | null {
+  const adj: Record<string, string[]> = {};
+  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: Record<string, number> = {};
+  for (const id of Object.keys(adj)) color[id] = WHITE;
+
+  const path: string[] = [];
+
+  function dfs(id: string): string[] | null {
+    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/lib/events.ts

@@ -40,16 +40,20 @@ export function formatReason(opts: { gate?: string; path?: string }): string | u
 
 /**
  * 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: string, params: StatusTransitionParams): string {
   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).
@@ -77,15 +81,16 @@ export function emitStatusTransition(repoRoot: string, params: StatusTransitionP
 
 /**
  * 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: string, params: GateDecisionParams): string {
   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: Record<string, unknown> = {

package/lib/ids.ts

@@ -13,10 +13,16 @@ export function nextTaskId(repoRoot: string, project: string): string {
   return `${project}-${String(next).padStart(3, '0')}`;
 }
 
-export function nextEventId(repoRoot: string, project: string): number {
+export function nextEventId(repoRoot: string, workItemId: string): number {
   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 is RegExpMatchArray => !!m)

package/lib/index.ts

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

package/lib/walk-state.ts

@@ -0,0 +1,39 @@
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname, join } from 'node:path';
+import type { WalkState } from './dag-walker.js';
+
+export function walkStatePath(repoRoot: string, planId: string): string {
+  return join(repoRoot, '.cloverleaf', 'runs', 'plan', planId, 'walk-state.json');
+}
+
+export function readWalkState(repoRoot: string, planId: string): WalkState | null {
+  const path = walkStatePath(repoRoot, planId);
+  if (!existsSync(path)) return null;
+  const raw = readFileSync(path, 'utf-8');
+  return JSON.parse(raw) as WalkState;
+}
+
+export function writeWalkState(repoRoot: string, state: WalkState): void {
+  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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloverleaf/reference-impl",
-  "version": "0.5.5",
+  "version": "0.6.0",
   "description": "Reference implementation of the Cloverleaf methodology as Claude Code skills. Implements the Tight Loop (Implementer + Reviewer).",
   "type": "module",
   "license": "MIT",
@@ -44,6 +44,7 @@
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
     "build": "tsc -p tsconfig.build.json && node scripts/rename-to-mjs.mjs",
+    "acceptance:walker": "bash scripts/acceptance-walker.sh",
     "prepublishOnly": "npm test && npm run build"
   },
   "dependencies": {

package/skills/cloverleaf-merge/SKILL.md

@@ -84,8 +84,16 @@ Report:
 
 ## Rules
 
-- Only proceed on explicit `y`, `Y`, `yes`, `YES`. Anything else: abort without state change.
+- Only proceed on explicit `y/Y/yes/YES`. Anything else is treated as either a decline (`n/N/no/NO`) or a clarifying question (see below).
 - The skill does NOT push the branch or open a PR.
 - Fast lane and full pipeline use distinct gates — the state machine records which path was taken.
 - Full-pipeline merges perform a real `git merge --no-ff` before advancing state — the feature branch's code, baselines, and feedback commits all land on main.
 - If the user declines, no state change and no commit.
+
+## Clarifying questions at final-gate
+
+If the user's response to the "Confirm merge? (y/N)" prompt is **not** one of `y/Y/yes/YES` or `n/N/no/NO`, treat it as a clarifying question. Answer it from the pipeline context available to you — the Reviewer/UI Reviewer/QA summaries, the diff, the task's ACs, the feedback files — and then **re-prompt** with the same y/N question.
+
+Loop this until the user gives a definitive y or n. Do not perform the merge until you see `y/Y/yes/YES`. Do not mark the task declined until you see `n/N/no/NO`.
+
+This keeps manual merges and walker-driven merges (`/cloverleaf-run-plan`) consistent: the user gets to interrogate the summary before committing.

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

@@ -0,0 +1,203 @@
+---
+name: cloverleaf-run-plan
+description: Autonomous DAG walker for Cloverleaf Plans. Given a PLAN-ID in status `gate-approved`, drives each task in the plan's task_dag through Delivery concurrently by spawning one claw-drive Session B per ready task. Default max_concurrent is 3. Surfaces only escalations and per-task final-gate approvals to the human. Resumable across invocations. Usage — /cloverleaf-run-plan <PLAN-ID> [--max-concurrent=N] [--reset].
+---
+
+# Cloverleaf — run-plan
+
+## Steps
+
+0. **Pre-flight.**
+
+   ```bash
+   cd <repo_root>
+   current=$(git rev-parse --abbrev-ref HEAD)
+   if [ "$current" != "main" ]; then git checkout main; fi
+   git status --short
+   ```
+
+   If `main` has uncommitted changes, stop and report — the user must clean up first.
+
+1. Capture the `<PLAN-ID>` argument and optional flags:
+
+   - `--max-concurrent=N` — cap simultaneous sessions. Default `3`. Setting `--max-concurrent=1` yields serial behaviour.
+   - `--reset` — wipe `.cloverleaf/runs/plan/<PLAN-ID>/walk-state.json` and start fresh.
+
+2. **Guard against cycles.**
+
+   ```bash
+   cloverleaf-cli dag-detect-cycle <repo_root> <PLAN-ID>
+   ```
+
+   If non-zero exit, stop. The malformed Plan needs to be fixed first.
+
+3. **Load or initialise walk-state.**
+
+   On `--reset`, `rm -f <repo_root>/.cloverleaf/runs/plan/<PLAN-ID>/walk-state.json`. Then:
+
+   ```bash
+   if ! cloverleaf-cli walk-state-read <repo_root> <PLAN-ID> > /tmp/walk-state-<PLAN-ID>.json 2>/dev/null; then
+     cat > /tmp/walk-state-<PLAN-ID>.json <<EOF
+   {
+     "plan_id": "<PLAN-ID>",
+     "started": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+     "max_concurrent": <MAX_CONCURRENT>,
+     "tasks": {}
+   }
+   EOF
+     cloverleaf-cli walk-state-write <repo_root> /tmp/walk-state-<PLAN-ID>.json
+   fi
+   ```
+
+4. **Resumability: reconcile running sessions.**
+
+   For each task in the walk-state with `state === "running"`:
+
+   - Query `claw-drive sessions` — is the session still live?
+     - **Still running** → keep it, start the watch monitor from `last_seq`.
+     - **Stopped cleanly** → check the task's on-disk status:
+       - `merged` → update walk-state `state: "merged"`.
+       - Anything else → mark `state: "pending"` for re-scheduling.
+     - **Stopped with error** → mark `state: "pending"`.
+
+   Atomic walk-state writes: every update goes through `cloverleaf-cli walk-state-write`.
+
+5. **Schedule loop.** Repeat until no running sessions AND no ready tasks:
+
+   a. **Compute ready tasks.**
+
+      ```bash
+      cloverleaf-cli dag-ready-tasks <repo_root> <PLAN-ID> <MAX_CONCURRENT>
+      ```
+
+      Returns a newline-separated list of task IDs that are `pending`, have all ancestors `merged`, and fit within free concurrency slots.
+
+   b. **For each ready task**, isolate it in its own git worktree and spawn a claw-drive Session B rooted in that worktree. A shared `cwd` across concurrent sessions is **unsafe** — each Session B's `/cloverleaf-run` mutates HEAD via `git checkout -b cloverleaf/<TASK-ID>`, and parallel Sessions on one working tree irreparably clobber each other's branches and state. Worktrees give each Session its own working directory so code + state commits on the task branch are fully isolated; the walker (in the primary repo, on `main`) handles the final merge serially.
+
+      Per ready task:
+
+      ```bash
+      WT="/tmp/walker-<PLAN-ID>-<TASK-ID>"
+      rm -rf "$WT"  # idempotent: clean any leftover from a prior run
+      git -C <repo_root> worktree add "$WT" -b cloverleaf/<TASK-ID> main
+      ```
+
+      Then `mcp__claw-drive__start_session` with:
+
+      - `cwd`: `$WT` (NOT `<repo_root>`)
+      - `decision_timeout_seconds`: `3600`
+      - `scenario_brief`: constructed for this task (see "Session brief template" below — critically, the brief instructs Session B to stop **before** invoking `/cloverleaf-merge`; the walker merges on main in step 5e).
+      - `policy`: the v0.6 walker policy (see "Walker policy" below).
+
+      Record the returned `session_id`, `worktree_path`, and `branch_name` in walk-state with `state: "running"`, `started_at: <now>`, `last_seq: 0`. Persist via `walk-state-write`.
+
+   c. **Monitor live sessions.** Start `claw-drive watch <session_id> --since <last_seq>` for each running session. Merge the streams into a single notification feed (e.g., the Monitor tool, or `claw-drive watch` run per-session in the background with a filter).
+
+   d. **Handle events.**
+
+      - **tool_decision_required** → let the walker policy decide (auto-approve per rules, defer to user for anything not covered).
+      - **turn_completed with final-gate prompt text** → push onto the final-gate queue.
+      - **Escalation detected** (assistant text contains `escalated` / Reviewer/QA/UI-Reviewer bounce cap / git merge abort) → **surface to user immediately** with:
+        > ⚠️ `<TASK-ID>` escalated at `<agent>` (reason: `<detail>`). Session `<session_id>`. Descendants in this Plan are now blocked until you unstick it.
+        > To unstick: read feedback at `.cloverleaf/feedback/<TASK-ID>-*.json`, fix the issue, and run `/cloverleaf-run <TASK-ID>` manually. The walker will re-check on its next tick — when the task reaches `merged`, it'll pick up descendants automatically.
+        Mark the task `state: "escalated"` in walk-state; do NOT queue it behind final-gate approvals; continue other branches.
+      - **session_stopped** → reconcile as in step 4.
+      - **Per-session idle > 30 min** → surface to user for inspection; do NOT auto-kill.
+
+   e. **Drain the final-gate queue serially and merge on main.** Session B does NOT invoke `/cloverleaf-merge` — it stops at automated-gates (fast lane) or final-gate (full pipeline) and reports. The walker performs the merge on main in the primary repo. For each queued task:
+
+      1. Print a full summary to the driver:
+         ```
+         ⏵ <TASK-ID> ready to merge (<fast lane | full pipeline>)
+           Reviewer: <summary>
+           UI Reviewer: <summary or "skipped">
+           QA: <summary or "n/a for fast lane">
+           Session <session_id>, worktree <worktree_path>
+
+           Confirm merge? (y/N, or ask a question)
+         ```
+      2. Read the user's response.
+      3. If it matches `^y(es)?$|^Y(ES)?$` → perform the merge in the primary repo:
+         ```bash
+         cd <repo_root>
+         git checkout main
+         git merge --no-ff cloverleaf/<TASK-ID> -m "cloverleaf: <TASK-ID> merged (<fast_lane | full_pipeline>)"
+         ```
+         Then advance state and commit:
+         ```bash
+         # Fast lane:
+         cloverleaf-cli emit-gate-decision <repo_root> <TASK-ID> human_merge approve human
+         cloverleaf-cli advance-status <repo_root> <TASK-ID> merged human human_merge fast_lane
+         # Full pipeline (task is already at final-gate):
+         cloverleaf-cli emit-gate-decision <repo_root> <TASK-ID> final_approval_gate approve human
+         cloverleaf-cli advance-status <repo_root> <TASK-ID> merged human final_approval_gate full_pipeline
+         ```
+         ```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.
+         **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.
+
+      Final-gate drain is strictly serial across tasks — one prompt, one decision, then the next. The merge itself is sequential on main for the same reason: two concurrent `git merge --no-ff` on main would race, even if the feature branches are independent.
+
+   f. **Exit check.** If no running sessions AND `dag-ready-tasks` returned empty AND the final-gate queue is empty, break the loop.
+
+6. **Report.**
+
+   - `merged: [ ... ]` — with merge-commit SHAs.
+   - `escalated: [ ... ]` — with reason per task.
+   - `awaiting_final_gate: [ ... ]` — user said `n`; re-invoke `/cloverleaf-merge <TASK-ID>` to retry.
+   - `unreachable: [ ... ]` — descendants of escalated tasks.
+
+   If every task in the plan's `task_dag.nodes` has `state: "merged"`, print: "✓ Plan `<PLAN-ID>` complete."
+
+## Session brief template
+
+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
+cloverleaf/<TASK-ID> (already created from main). Task risk_class: <class>.
+
+Plan: invoke `/cloverleaf-run <TASK-ID>`.
+
+**DO NOT invoke `/cloverleaf-merge`**. Fast lane stops after `/cloverleaf-review`
+lands the task at `automated-gates`. Full pipeline stops after QA/UI-Review
+lands the task at `final-gate`. Report status + summaries at that point and
+exit cleanly. The walker runs in the primary repo on `main` and performs the
+real `git merge --no-ff` itself after human approval — the worktree's main
+branch can't be checked out concurrently, which is why the walker owns the
+merge. If `/cloverleaf-run` would normally invoke `/cloverleaf-merge`
+internally (fast-lane orchestrator), interrupt before that step and exit.
+
+All four v0.5.2+v0.5.3+v0.5.4+v0.5.5 dogfood fixes are in place:
+- /cloverleaf-merge actor: human final_approval_gate full_pipeline.
+- cloverleaf-cli prep-worktree is idempotent.
+- Documenter runs `git status --porcelain` and stages every modified doc.
+- cloverleaf-ui-review uses /cloverleaf-approve-baselines (fully-qualified).
+
+Expected: zero interventions until you reach automated-gates / final-gate,
+then exit.
+
+Do not push. Do not publish. Report merge + state commit SHAs on completion.
+```
+
+## Walker policy
+
+The walker spawns each Session B with a conservative auto-approve policy (Read/Glob/Grep, git-read, cloverleaf-cli, npm/npx/node, common compound scripts, prep-worktree, mkdir -p, etc.) and an auto-reject list covering sudo, `rm -rf /`, git push, npm publish, destructive disk ops. Anything else escalates to the walker for human-in-the-loop handling.
+
+The concrete policy JSON is the same one used during the CLV-16..CLV-20 dogfood runs; see `.cloverleaf/claw-drive-policy.json` in the repo for the starting template.
+
+## Rules
+
+- Never push. Never publish.
+- Always persist walk-state via `cloverleaf-cli walk-state-write` (atomic). Never write the file directly.
+- Always treat the on-disk `.cloverleaf/tasks/<id>.json` status as the source of truth AFTER a task's branch has been merged; before that, the task's state lives on `cloverleaf/<TASK-ID>` in its worktree (walk-state is authoritative for the walker's scheduling decisions during the walk).
+- **Every ready task runs in its own git worktree.** Sharing `cwd` across concurrent sessions is unsafe — parallel `git checkout` / `commit` races corrupt branches and state. The walker creates a worktree per task, passes it to Session B as `cwd`, and owns the final merge serially on main.
+- Session B must NOT invoke `/cloverleaf-merge`. The walker performs the merge in the primary repo, on main, as the authoritative merge-performer.
+- Escalations surface immediately; they do NOT queue behind the final-gate drain.
+- Final-gate drain is serial across tasks — one prompt, one decision.
+- The walker exits after the loop reports the final status; it does not auto-retry escalated tasks.