@cloverleaf/reference-impl 0.6.7 → 0.7.0

package/README.md

@@ -153,7 +153,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`. 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. `lib/walker-config.ts` exports `loadWalkerConfig()` — reads `~/.config/cloverleaf/walker.json` (XDG-aware) for the user-level `max_concurrent` override; exposed via `cloverleaf-cli walker-default-concurrency [--explain]`. `lib/release-preflight.ts` exports `runPreflightChecks(repoRoot)` — runs six blocking checks and two warnings, returning `{ checks, version, tag, notes }`; exposed via `cloverleaf-cli release-preflight <repoRoot> [--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. `lib/walker-config.ts` exports `loadWalkerConfig()` — reads `~/.config/cloverleaf/walker.json` (XDG-aware) for the user-level `max_concurrent` override; exposed via `cloverleaf-cli walker-default-concurrency [--explain]`. `lib/release-preflight.ts` exports `runPreflightChecks(repoRoot)` — runs six blocking checks and two warnings, returning `{ checks, version, tag, notes }`; exposed via `cloverleaf-cli release-preflight <repoRoot> [--json]`. `lib/dag-overlap.ts` exports `computeOverlapEdges(tasks)` and `getFirstSharedFile(taskA, taskB)` — infers serialization edges from `scope.files_touched` and is used internally by `savePlan` to augment `task_dag.edges` before writing.
 - `skills/` — Claude Code skill markdown files.
 - `prompts/` — Implementer/Reviewer subagent system prompts.
 - `examples/toy-repo/` — standalone demo repo.

package/dist/dag-overlap.mjs

@@ -0,0 +1,132 @@
+/**
+ * dag-overlap.ts — reference-impl v0.7.0
+ *
+ * Infers TaskDag serialization edges from shared `scope.files_touched` paths.
+ * Two tasks that touch the same file must be serialized to avoid merge conflicts.
+ *
+ * Algorithm:
+ *  1. For each task, extract `scope?.files_touched` (absent / empty → zero contribution).
+ *  2. Normalize each path: strip leading `./`, collapse multiple leading `./`, strip
+ *     trailing `/`, canonicalize separators to forward-slash.
+ *  3. Enumerate all (i, j) pairs where i < j (by task index). For each pair, compute
+ *     the intersection of their normalized file sets.
+ *  4. For each intersecting pair, emit one edge: lower-id (lexicographic) → higher-id.
+ *  5. Deduplicate edges by (from.id, to.id) — a pair can share multiple files, but
+ *     only one edge is emitted per unique (from, to) combination.
+ *  6. Sort output by (from.id, to.id) for deterministic ordering.
+ */
+/**
+ * Normalize a raw file path from `scope.files_touched`.
+ *
+ * Rules (applied in order):
+ *  - Trim whitespace
+ *  - Replace backslashes with forward-slashes
+ *  - Strip any number of leading `./` sequences
+ *  - Strip trailing `/`
+ *  - Return the resulting string (may be empty for degenerate inputs; caller filters)
+ */
+function normalizePath(p) {
+    let s = p.trim().replace(/\\/g, '/');
+    // Strip leading `./` repeatedly
+    while (s.startsWith('./')) {
+        s = s.slice(2);
+    }
+    // Strip trailing `/`
+    while (s.endsWith('/') && s.length > 1) {
+        s = s.slice(0, -1);
+    }
+    return s;
+}
+/**
+ * Extract and normalize `scope.files_touched` from a task document.
+ * Returns an empty array if the field is absent, null, or empty.
+ */
+function getFiles(task) {
+    const scope = task['scope'];
+    if (!scope)
+        return [];
+    const files = scope['files_touched'];
+    if (!Array.isArray(files))
+        return [];
+    const normalized = [];
+    for (const f of files) {
+        if (typeof f !== 'string')
+            continue;
+        const n = normalizePath(f);
+        if (n.length > 0)
+            normalized.push(n);
+    }
+    return normalized;
+}
+/**
+ * Compute the canonical overlap edge (from → to) for a pair of tasks.
+ * The edge always points from the lexicographically lower id to the higher id.
+ */
+function makeEdgeRef(projectA, idA, projectB, idB) {
+    if (idA <= idB) {
+        return { from: { project: projectA, id: idA }, to: { project: projectB, id: idB } };
+    }
+    return { from: { project: projectB, id: idB }, to: { project: projectA, id: idA } };
+}
+/**
+ * Compute overlap-inferred DAG edges from a list of task documents.
+ *
+ * Returns a deterministically ordered, deduplicated list of `TaskDagEdge`
+ * values — one edge per (from.id, to.id) pair that shares at least one
+ * normalized file path.
+ *
+ * Input order is irrelevant; output order is sorted by (from.id, to.id).
+ */
+export function computeOverlapEdges(tasks) {
+    if (tasks.length < 2)
+        return [];
+    // Build a map: taskIndex → normalized file set
+    const fileSets = tasks.map(t => new Set(getFiles(t)));
+    // Collect edges using a map keyed by "fromId|toId" for deduplication
+    const edgeMap = new Map();
+    for (let i = 0; i < tasks.length; i++) {
+        for (let j = i + 1; j < tasks.length; j++) {
+            const setA = fileSets[i];
+            const setB = fileSets[j];
+            if (setA.size === 0 || setB.size === 0)
+                continue;
+            // Check intersection
+            let hasOverlap = false;
+            for (const f of setA) {
+                if (setB.has(f)) {
+                    hasOverlap = true;
+                    break;
+                }
+            }
+            if (!hasOverlap)
+                continue;
+            const taskA = tasks[i];
+            const taskB = tasks[j];
+            const edge = makeEdgeRef(taskA.project, taskA.id, taskB.project, taskB.id);
+            const key = `${edge.from.id}|${edge.to.id}`;
+            if (!edgeMap.has(key)) {
+                edgeMap.set(key, edge);
+            }
+        }
+    }
+    // Sort for determinism: by from.id, then to.id
+    const edges = Array.from(edgeMap.values());
+    edges.sort((a, b) => {
+        const c = a.from.id.localeCompare(b.from.id);
+        return c !== 0 ? c : a.to.id.localeCompare(b.to.id);
+    });
+    return edges;
+}
+/**
+ * Return true if task A and task B share at least one normalized file path.
+ * Used by savePlan to report which file caused the cycle.
+ */
+export function getFirstSharedFile(taskA, taskB) {
+    const setA = new Set(getFiles(taskA));
+    const filesB = getFiles(taskB);
+    for (const f of filesB) {
+        if (setA.has(f))
+            return f;
+    }
+    return null;
+}

package/dist/plan.mjs

@@ -3,6 +3,7 @@ import { join } from 'node:path';
 import { plansDir, tasksDir } from './paths.mjs';
 import { validateOrThrow } from './validate.mjs';
 import { advanceWorkItemStatus, loadStateMachine } from './work-item.mjs';
+import { computeOverlapEdges, getFirstSharedFile } from './dag-overlap.mjs';
 export function loadPlan(repoRoot, id) {
     const path = join(plansDir(repoRoot), `${id}.json`);
     if (!existsSync(path))
@@ -10,7 +11,55 @@ export function loadPlan(repoRoot, id) {
     return JSON.parse(readFileSync(path, 'utf-8'));
 }
 export function savePlan(repoRoot, plan) {
+    // 1. Schema validation.
     validateOrThrow('https://cloverleaf.example/schemas/plan.schema.json', plan);
+    // 2. Compute overlap-inferred edges from task scope.files_touched and
+    //    merge them into task_dag.edges via set-union (idempotent).
+    const tasks = plan.tasks;
+    const overlapEdges = computeOverlapEdges(tasks);
+    if (overlapEdges.length > 0) {
+        const existingKeys = new Set(plan.task_dag.edges.map(e => `${e.from.id}|${e.to.id}`));
+        const newEdges = overlapEdges.filter(e => !existingKeys.has(`${e.from.id}|${e.to.id}`));
+        if (newEdges.length > 0) {
+            plan = {
+                ...plan,
+                task_dag: {
+                    ...plan.task_dag,
+                    edges: [...plan.task_dag.edges, ...newEdges],
+                },
+            };
+        }
+    }
+    // 3. Cycle detection on the augmented DAG. Only triggered when overlap
+    //    edges are present — if computeOverlapEdges emitted any edges, we
+    //    must verify the merged graph is acyclic. Report which pair and which
+    //    file caused the cycle.
+    if (overlapEdges.length > 0) {
+        const cycleNodeId = detectCycle(plan.task_dag);
+        if (cycleNodeId !== null) {
+            // Find the two tasks involved in the cycle that share a file.
+            const taskMap = new Map();
+            for (const t of tasks)
+                taskMap.set(t.id, t);
+            let errorMsg = `file overlap creates cycle: ${cycleNodeId} ↔ (unknown) via (unknown)`;
+            // Try to find a concrete overlap pair that touches the cycle node.
+            outer: for (const edge of overlapEdges) {
+                const tFrom = taskMap.get(edge.from.id);
+                const tTo = taskMap.get(edge.to.id);
+                if (!tFrom || !tTo)
+                    continue;
+                if (edge.from.id !== cycleNodeId && edge.to.id !== cycleNodeId)
+                    continue;
+                const sharedFile = getFirstSharedFile(tFrom, tTo);
+                if (sharedFile) {
+                    errorMsg = `file overlap creates cycle: ${edge.from.id} ↔ ${edge.to.id} via ${sharedFile}`;
+                    break outer;
+                }
+            }
+            throw new Error(errorMsg);
+        }
+    }
+    // 4. Write to disk.
     mkdirSync(plansDir(repoRoot), { recursive: true });
     const path = join(plansDir(repoRoot), `${plan.id}.json`);
     writeFileSync(path, JSON.stringify(plan, null, 2) + '\n');

package/lib/dag-overlap.ts

@@ -0,0 +1,155 @@
+/**
+ * dag-overlap.ts — reference-impl v0.7.0
+ *
+ * Infers TaskDag serialization edges from shared `scope.files_touched` paths.
+ * Two tasks that touch the same file must be serialized to avoid merge conflicts.
+ *
+ * Algorithm:
+ *  1. For each task, extract `scope?.files_touched` (absent / empty → zero contribution).
+ *  2. Normalize each path: strip leading `./`, collapse multiple leading `./`, strip
+ *     trailing `/`, canonicalize separators to forward-slash.
+ *  3. Enumerate all (i, j) pairs where i < j (by task index). For each pair, compute
+ *     the intersection of their normalized file sets.
+ *  4. For each intersecting pair, emit one edge: lower-id (lexicographic) → higher-id.
+ *  5. Deduplicate edges by (from.id, to.id) — a pair can share multiple files, but
+ *     only one edge is emitted per unique (from, to) combination.
+ *  6. Sort output by (from.id, to.id) for deterministic ordering.
+ */
+
+import type { TaskDoc } from './task.js';
+
+// Re-export the shape used in plan.ts so callers can use one import.
+export interface TaskDagEdgeRef {
+  project: string;
+  id: string;
+}
+
+export interface TaskDagEdge {
+  from: TaskDagEdgeRef;
+  to: TaskDagEdgeRef;
+}
+
+/**
+ * Normalize a raw file path from `scope.files_touched`.
+ *
+ * Rules (applied in order):
+ *  - Trim whitespace
+ *  - Replace backslashes with forward-slashes
+ *  - Strip any number of leading `./` sequences
+ *  - Strip trailing `/`
+ *  - Return the resulting string (may be empty for degenerate inputs; caller filters)
+ */
+function normalizePath(p: string): string {
+  let s = p.trim().replace(/\\/g, '/');
+  // Strip leading `./` repeatedly
+  while (s.startsWith('./')) {
+    s = s.slice(2);
+  }
+  // Strip trailing `/`
+  while (s.endsWith('/') && s.length > 1) {
+    s = s.slice(0, -1);
+  }
+  return s;
+}
+
+/**
+ * Extract and normalize `scope.files_touched` from a task document.
+ * Returns an empty array if the field is absent, null, or empty.
+ */
+function getFiles(task: TaskDoc): string[] {
+  const scope = task['scope'] as Record<string, unknown> | undefined;
+  if (!scope) return [];
+  const files = scope['files_touched'];
+  if (!Array.isArray(files)) return [];
+  const normalized: string[] = [];
+  for (const f of files) {
+    if (typeof f !== 'string') continue;
+    const n = normalizePath(f);
+    if (n.length > 0) normalized.push(n);
+  }
+  return normalized;
+}
+
+/**
+ * Compute the canonical overlap edge (from → to) for a pair of tasks.
+ * The edge always points from the lexicographically lower id to the higher id.
+ */
+function makeEdgeRef(
+  projectA: string, idA: string,
+  projectB: string, idB: string
+): { from: TaskDagEdgeRef; to: TaskDagEdgeRef } {
+  if (idA <= idB) {
+    return { from: { project: projectA, id: idA }, to: { project: projectB, id: idB } };
+  }
+  return { from: { project: projectB, id: idB }, to: { project: projectA, id: idA } };
+}
+
+/**
+ * Compute overlap-inferred DAG edges from a list of task documents.
+ *
+ * Returns a deterministically ordered, deduplicated list of `TaskDagEdge`
+ * values — one edge per (from.id, to.id) pair that shares at least one
+ * normalized file path.
+ *
+ * Input order is irrelevant; output order is sorted by (from.id, to.id).
+ */
+export function computeOverlapEdges(tasks: TaskDoc[]): TaskDagEdge[] {
+  if (tasks.length < 2) return [];
+
+  // Build a map: taskIndex → normalized file set
+  const fileSets: Array<Set<string>> = tasks.map(t => new Set(getFiles(t)));
+
+  // Collect edges using a map keyed by "fromId|toId" for deduplication
+  const edgeMap = new Map<string, TaskDagEdge>();
+
+  for (let i = 0; i < tasks.length; i++) {
+    for (let j = i + 1; j < tasks.length; j++) {
+      const setA = fileSets[i];
+      const setB = fileSets[j];
+      if (setA.size === 0 || setB.size === 0) continue;
+
+      // Check intersection
+      let hasOverlap = false;
+      for (const f of setA) {
+        if (setB.has(f)) {
+          hasOverlap = true;
+          break;
+        }
+      }
+      if (!hasOverlap) continue;
+
+      const taskA = tasks[i];
+      const taskB = tasks[j];
+      const edge = makeEdgeRef(
+        taskA.project, taskA.id,
+        taskB.project, taskB.id
+      );
+      const key = `${edge.from.id}|${edge.to.id}`;
+      if (!edgeMap.has(key)) {
+        edgeMap.set(key, edge);
+      }
+    }
+  }
+
+  // Sort for determinism: by from.id, then to.id
+  const edges = Array.from(edgeMap.values());
+  edges.sort((a, b) => {
+    const c = a.from.id.localeCompare(b.from.id);
+    return c !== 0 ? c : a.to.id.localeCompare(b.to.id);
+  });
+
+  return edges;
+}
+
+/**
+ * Return true if task A and task B share at least one normalized file path.
+ * Used by savePlan to report which file caused the cycle.
+ */
+export function getFirstSharedFile(taskA: TaskDoc, taskB: TaskDoc): string | null {
+  const setA = new Set(getFiles(taskA));
+  const filesB = getFiles(taskB);
+  for (const f of filesB) {
+    if (setA.has(f)) return f;
+  }
+  return null;
+}

package/lib/plan.ts

@@ -3,6 +3,8 @@ import { join } from 'node:path';
 import { plansDir, tasksDir } from './paths.js';
 import { validateOrThrow } from './validate.js';
 import { advanceWorkItemStatus, loadStateMachine } from './work-item.js';
+import { computeOverlapEdges, getFirstSharedFile } from './dag-overlap.js';
+import type { TaskDoc } from './task.js';
 
 export interface WorkItemRef {
   project: string;
@@ -34,7 +36,59 @@ export function loadPlan(repoRoot: string, id: string): PlanDoc {
 }
 
 export function savePlan(repoRoot: string, plan: PlanDoc): void {
+  // 1. Schema validation.
   validateOrThrow('https://cloverleaf.example/schemas/plan.schema.json', plan);
+
+  // 2. Compute overlap-inferred edges from task scope.files_touched and
+  //    merge them into task_dag.edges via set-union (idempotent).
+  const tasks = plan.tasks as unknown as TaskDoc[];
+  const overlapEdges = computeOverlapEdges(tasks);
+  if (overlapEdges.length > 0) {
+    const existingKeys = new Set(
+      plan.task_dag.edges.map(e => `${e.from.id}|${e.to.id}`)
+    );
+    const newEdges = overlapEdges.filter(
+      e => !existingKeys.has(`${e.from.id}|${e.to.id}`)
+    );
+    if (newEdges.length > 0) {
+      plan = {
+        ...plan,
+        task_dag: {
+          ...plan.task_dag,
+          edges: [...plan.task_dag.edges, ...newEdges],
+        },
+      };
+    }
+  }
+
+  // 3. Cycle detection on the augmented DAG. Only triggered when overlap
+  //    edges are present — if computeOverlapEdges emitted any edges, we
+  //    must verify the merged graph is acyclic. Report which pair and which
+  //    file caused the cycle.
+  if (overlapEdges.length > 0) {
+    const cycleNodeId = detectCycle(plan.task_dag);
+    if (cycleNodeId !== null) {
+      // Find the two tasks involved in the cycle that share a file.
+      const taskMap = new Map<string, TaskDoc>();
+      for (const t of tasks) taskMap.set(t.id, t);
+      let errorMsg = `file overlap creates cycle: ${cycleNodeId} ↔ (unknown) via (unknown)`;
+      // Try to find a concrete overlap pair that touches the cycle node.
+      outer: for (const edge of overlapEdges) {
+        const tFrom = taskMap.get(edge.from.id);
+        const tTo = taskMap.get(edge.to.id);
+        if (!tFrom || !tTo) continue;
+        if (edge.from.id !== cycleNodeId && edge.to.id !== cycleNodeId) continue;
+        const sharedFile = getFirstSharedFile(tFrom, tTo);
+        if (sharedFile) {
+          errorMsg = `file overlap creates cycle: ${edge.from.id} ↔ ${edge.to.id} via ${sharedFile}`;
+          break outer;
+        }
+      }
+      throw new Error(errorMsg);
+    }
+  }
+
+  // 4. Write to disk.
   mkdirSync(plansDir(repoRoot), { recursive: true });
   const path = join(plansDir(repoRoot), `${plan.id}.json`);
   writeFileSync(path, JSON.stringify(plan, null, 2) + '\n');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloverleaf/reference-impl",
-  "version": "0.6.7",
+  "version": "0.7.0",
   "description": "Reference implementation of the Cloverleaf methodology as Claude Code skills. Implements the Tight Loop (Implementer + Reviewer).",
   "type": "module",
   "license": "MIT",
@@ -48,7 +48,7 @@
     "prepublishOnly": "node scripts/check-standard-prepped.mjs && npm test && npm run build"
   },
   "dependencies": {
-    "@cloverleaf/standard": "^0.4.0",
+    "@cloverleaf/standard": "^0.5.0",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
     "axe-core": "^4.10.0",

package/prompts/plan.md

@@ -27,7 +27,9 @@ You are the Plan Agent. Your role is to take an approved RFC and its completed S
 4. Build a `task_dag` using the edge-based shape from `dependency-dag.schema.json`:
    - `nodes: Array<{project, id}>` — one workItemRef per task in `tasks[]`.
    - `edges: Array<{from: {project, id}, to: {project, id}}>` — directed edges from prerequisite to dependent. `to` cannot start until `from` completes. Both endpoints must appear in `nodes`. DAG roots are nodes that appear in no edge's `to` field.
-5. If `path_rules` is non-empty, emit `path_reviewer_map: Array<{pattern, role}>` by mapping the rules' path globs to reviewer roles.
+   - Only add edges for **logical** sequencing dependencies (e.g. task B cannot start until task A's output exists). **Do NOT manually add edges for file overlap. The system computes them automatically when the Plan is saved.**
+5. For each task in `tasks[]`, populate `scope.files_touched` with the repo-root-relative POSIX paths of every file the task is expected to create or modify. Transcribe these paths directly from the brief's Parallel-DAG conflict guidance section; if the brief does not list specific paths for a task, include a best-effort list based on the task's definition of done. Example: `"scope": { "files_touched": ["reference-impl/lib/cli.ts", "reference-impl/lib/auth.ts"] }`.
+6. If `path_rules` is non-empty, emit `path_reviewer_map: Array<{pattern, role}>` by mapping the rules' path globs to reviewer roles.
 
 ## Emit a Plan JSON conforming to `plan.schema.json`
 
@@ -61,3 +63,29 @@ Write the Plan JSON to stdout, nothing else. No prose, no markdown fences. The o
 - **Schema compliance is mandatory.** Each task in `tasks[]` must independently pass `task.schema.json` validation.
 - **No file writes.** Orchestrator persists your output.
 - Gate for Plan approval: `task_batch_gate` (approved by human after `gate-pending`).
+
+## Gate-pending summary template
+
+When the orchestrator transitions the Plan to `gate-pending`, include a human-readable summary of the proposed task graph. Use the following template, computing the edge groupings inline before emitting:
+
+```
+Plan <PLAN-ID> — gate-pending
+
+Tasks (<N> total):
+  <TASK-ID>  <task title>  [<risk_class>]
+  ...
+
+Dependencies:
+  Logical:
+    <FROM-ID> → <TO-ID>   (<reason, e.g. "B needs A's migration output">)
+    ...
+  Inferred from file overlap:
+    <FROM-ID> → <TO-ID>   (shared: <comma-separated overlapping file paths>)
+    ...
+
+  (None) — use "(None)" under a subsection when it is empty.
+```
+
+**How to compute the diff inline:**
+- **Logical** edges: edges you explicitly declared in `task_dag.edges` for sequencing reasons.
+- **Inferred from file overlap**: edges the system will auto-compute by comparing `scope.files_touched` across tasks. For the summary, compute these yourself: for each pair of tasks (A, B) where A has lower task-number, if `scope.files_touched` sets overlap, list an inferred edge A → B with the overlapping paths. Do NOT add these to `task_dag.edges` — list them only in this summary so the human can sanity-check before approval.