@cloverleaf/reference-impl 0.5.5 → 0.6.1

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/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/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.1",
   "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/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-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.