@cloverleaf/reference-impl 0.6.6 → 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/cli.mjs

@@ -35,12 +35,10 @@
  *   walk-state-read <repoRoot> <planId>
  *   walk-state-write <repoRoot> <walkStateJsonPath>
  *   walker-default-concurrency [--explain]
- *   release-preflight <repoRoot> [--json]
  */
 import { readFileSync, mkdirSync, copyFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { execSync } from 'node:child_process';
-import { runPreflightChecks } from './release-preflight.mjs';
 import { loadTask } from './task.mjs';
 import { advanceStatus } from './task.mjs';
 import { emitGateDecision } from './events.mjs';
@@ -110,11 +108,14 @@ if (!command) {
 try {
     switch (command) {
         case 'load-task': {
-            const [repoRoot, taskId] = rest;
+            const positional = rest.filter((a) => !a.startsWith('--'));
+            const flags = rest.filter((a) => a.startsWith('--'));
+            const [repoRoot, taskId] = positional;
             if (!repoRoot || !taskId)
                 usage('load-task requires <repoRoot> <taskId>');
+            const pretty = flags.includes('--pretty');
             const task = loadTask(repoRoot, taskId);
-            process.stdout.write(JSON.stringify(task, null, 2) + '\n');
+            process.stdout.write((pretty ? JSON.stringify(task, null, 2) : JSON.stringify(task)) + '\n');
             break;
         }
         case 'infer-project': {
@@ -333,10 +334,14 @@ try {
             process.exit(0);
         }
         case 'load-rfc': {
-            const [repoRoot, id] = rest;
+            const positional = rest.filter((a) => !a.startsWith('--'));
+            const flags = rest.filter((a) => a.startsWith('--'));
+            const [repoRoot, id] = positional;
             if (!repoRoot || !id)
                 usage('load-rfc <repoRoot> <id>');
-            process.stdout.write(JSON.stringify(loadRfc(repoRoot, id), null, 2));
+            const pretty = flags.includes('--pretty');
+            const doc = loadRfc(repoRoot, id);
+            process.stdout.write((pretty ? JSON.stringify(doc, null, 2) : JSON.stringify(doc)) + '\n');
             break;
         }
         case 'save-rfc': {
@@ -358,10 +363,14 @@ try {
             break;
         }
         case 'load-spike': {
-            const [repoRoot, id] = rest;
+            const positional = rest.filter((a) => !a.startsWith('--'));
+            const flags = rest.filter((a) => a.startsWith('--'));
+            const [repoRoot, id] = positional;
             if (!repoRoot || !id)
                 usage('load-spike <repoRoot> <id>');
-            process.stdout.write(JSON.stringify(loadSpike(repoRoot, id), null, 2));
+            const pretty = flags.includes('--pretty');
+            const doc = loadSpike(repoRoot, id);
+            process.stdout.write((pretty ? JSON.stringify(doc, null, 2) : JSON.stringify(doc)) + '\n');
             break;
         }
         case 'save-spike': {
@@ -382,10 +391,14 @@ try {
             break;
         }
         case 'load-plan': {
-            const [repoRoot, id] = rest;
+            const positional = rest.filter((a) => !a.startsWith('--'));
+            const flags = rest.filter((a) => a.startsWith('--'));
+            const [repoRoot, id] = positional;
             if (!repoRoot || !id)
                 usage('load-plan <repoRoot> <id>');
-            process.stdout.write(JSON.stringify(loadPlan(repoRoot, id), null, 2));
+            const pretty = flags.includes('--pretty');
+            const doc = loadPlan(repoRoot, id);
+            process.stdout.write((pretty ? JSON.stringify(doc, null, 2) : JSON.stringify(doc)) + '\n');
             break;
         }
         case 'save-plan': {
@@ -510,37 +523,6 @@ try {
             }
             process.exit(0);
         }
-        case 'release-preflight': {
-            const positional = rest.filter((a) => !a.startsWith('--'));
-            const flags = rest.filter((a) => a.startsWith('--'));
-            const [repoRoot] = positional;
-            if (!repoRoot)
-                usage('release-preflight requires <repoRoot>');
-            const jsonMode = flags.includes('--json');
-            const result = runPreflightChecks(repoRoot);
-            if (jsonMode) {
-                process.stdout.write(JSON.stringify(result, null, 2) + '\n');
-                process.exit(0);
-            }
-            else {
-                // Plain human-readable mode
-                for (const check of result.checks) {
-                    let prefix;
-                    if (check.status === 'pass') {
-                        prefix = '✓';
-                    }
-                    else if (check.level === 'warning') {
-                        prefix = '⚠';
-                    }
-                    else {
-                        prefix = '✗';
-                    }
-                    process.stdout.write(`${prefix} ${check.id}: ${check.message}\n`);
-                }
-                const blockingFailed = result.checks.some((c) => c.level === 'blocking' && c.status === 'fail');
-                process.exit(blockingFailed ? 1 : 0);
-            }
-        }
         default:
             usage(`Unknown command: ${command}`);
     }

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/cli.ts

@@ -35,13 +35,11 @@
  *   walk-state-read <repoRoot> <planId>
  *   walk-state-write <repoRoot> <walkStateJsonPath>
  *   walker-default-concurrency [--explain]
- *   release-preflight <repoRoot> [--json]
  */
 
 import { readFileSync, mkdirSync, copyFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { execSync } from 'node:child_process';
-import { runPreflightChecks } from './release-preflight.js';
 import { loadTask } from './task.js';
 import { advanceStatus } from './task.js';
 import { emitGateDecision } from './events.js';
@@ -118,10 +116,13 @@ if (!command) {
 try {
   switch (command) {
     case 'load-task': {
-      const [repoRoot, taskId] = rest;
+      const positional = rest.filter((a) => !a.startsWith('--'));
+      const flags = rest.filter((a) => a.startsWith('--'));
+      const [repoRoot, taskId] = positional;
       if (!repoRoot || !taskId) usage('load-task requires <repoRoot> <taskId>');
+      const pretty = flags.includes('--pretty');
       const task = loadTask(repoRoot, taskId);
-      process.stdout.write(JSON.stringify(task, null, 2) + '\n');
+      process.stdout.write((pretty ? JSON.stringify(task, null, 2) : JSON.stringify(task)) + '\n');
       break;
     }
 
@@ -349,9 +350,13 @@ try {
     }
 
     case 'load-rfc': {
-      const [repoRoot, id] = rest;
+      const positional = rest.filter((a) => !a.startsWith('--'));
+      const flags = rest.filter((a) => a.startsWith('--'));
+      const [repoRoot, id] = positional;
       if (!repoRoot || !id) usage('load-rfc <repoRoot> <id>');
-      process.stdout.write(JSON.stringify(loadRfc(repoRoot, id), null, 2));
+      const pretty = flags.includes('--pretty');
+      const doc = loadRfc(repoRoot, id);
+      process.stdout.write((pretty ? JSON.stringify(doc, null, 2) : JSON.stringify(doc)) + '\n');
       break;
     }
 
@@ -373,9 +378,13 @@ try {
     }
 
     case 'load-spike': {
-      const [repoRoot, id] = rest;
+      const positional = rest.filter((a) => !a.startsWith('--'));
+      const flags = rest.filter((a) => a.startsWith('--'));
+      const [repoRoot, id] = positional;
       if (!repoRoot || !id) usage('load-spike <repoRoot> <id>');
-      process.stdout.write(JSON.stringify(loadSpike(repoRoot, id), null, 2));
+      const pretty = flags.includes('--pretty');
+      const doc = loadSpike(repoRoot, id);
+      process.stdout.write((pretty ? JSON.stringify(doc, null, 2) : JSON.stringify(doc)) + '\n');
       break;
     }
 
@@ -396,9 +405,13 @@ try {
     }
 
     case 'load-plan': {
-      const [repoRoot, id] = rest;
+      const positional = rest.filter((a) => !a.startsWith('--'));
+      const flags = rest.filter((a) => a.startsWith('--'));
+      const [repoRoot, id] = positional;
       if (!repoRoot || !id) usage('load-plan <repoRoot> <id>');
-      process.stdout.write(JSON.stringify(loadPlan(repoRoot, id), null, 2));
+      const pretty = flags.includes('--pretty');
+      const doc = loadPlan(repoRoot, id);
+      process.stdout.write((pretty ? JSON.stringify(doc, null, 2) : JSON.stringify(doc)) + '\n');
       break;
     }
 
@@ -524,36 +537,6 @@ try {
       process.exit(0);
     }
 
-    case 'release-preflight': {
-      const positional = rest.filter((a) => !a.startsWith('--'));
-      const flags = rest.filter((a) => a.startsWith('--'));
-      const [repoRoot] = positional;
-      if (!repoRoot) usage('release-preflight requires <repoRoot>');
-      const jsonMode = flags.includes('--json');
-      const result = runPreflightChecks(repoRoot);
-      if (jsonMode) {
-        process.stdout.write(JSON.stringify(result, null, 2) + '\n');
-        process.exit(0);
-      } else {
-        // Plain human-readable mode
-        for (const check of result.checks) {
-          let prefix: string;
-          if (check.status === 'pass') {
-            prefix = '✓';
-          } else if (check.level === 'warning') {
-            prefix = '⚠';
-          } else {
-            prefix = '✗';
-          }
-          process.stdout.write(`${prefix} ${check.id}: ${check.message}\n`);
-        }
-        const blockingFailed = result.checks.some(
-          (c) => c.level === 'blocking' && c.status === 'fail',
-        );
-        process.exit(blockingFailed ? 1 : 0);
-      }
-    }
-
     default:
       usage(`Unknown command: ${command}`);
   }

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.6",
+  "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.

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

@@ -111,23 +111,61 @@ description: Autonomous DAG walker for Cloverleaf Plans. Given a PLAN-ID in stat
 
       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> --idle-after 600` 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). The `--idle-after 600` flag instructs claw-drive to emit a synthetic `idle` event if a session produces no output for 600 seconds (10 minutes), enabling the walker to detect stalled sessions without polling.
+      Immediately after `mcp__claw-drive__start_session` returns, attach a Monitor tool stream for the new session:
 
-   d. **Handle events.**
+      ```
+      Monitor(
+        watch_command: "claw-drive watch <session_id> --since 0 --idle-after 600",
+        persistent: true,
+        timeout_ms: 3600000
+      )
+      ```
+
+      This ensures the walker receives all child events without requiring Session A nudges. The `persistent: true` flag keeps the stream open across turns; `timeout_ms: 3600000` caps the watch at one hour.
+
+   c. **Monitor live sessions.** Each child session is already watched via the persistent Monitor stream attached in step 5b. When resuming after a walker restart (step 4), re-attach the Monitor with `--since <last_seq>` for each session still in `state: "running"`:
+
+      ```
+      Monitor(
+        watch_command: "claw-drive watch <session_id> --since <last_seq> --idle-after 600",
+        persistent: true,
+        timeout_ms: 3600000
+      )
+      ```
+
+      The `--idle-after 600` flag instructs claw-drive to emit a synthetic `idle` event if a session produces no output for 600 seconds (10 minutes), enabling the walker to detect stalled sessions without polling.
+
+   d. **Handle events.** Dispatch each incoming Monitor event by type:
+
+      - **`idle`** (`silent_for_ms >= 600000`) — the session has been silent for 10 minutes. For each child session emitting this event, check terminal state:
+        ```bash
+        claw-drive status <child_session_id>
+        ```
+        Read `last_token` from the status response, then branch:
+        - `last_token` is `[DONE]` → treat as terminal; proceed with drain (same as `session_stopped` → stopped cleanly).
+        - `last_token` is `[NEEDS-INPUT]` → the session is waiting for user input; surface to the user for a decision and send a reply via `mcp__claw-drive__send_turn`.
+        - Status output matches the transient-5xx pattern (`5\d\d\b`, `API Error: 5\d\d`, or `temporarily unavailable`) → invoke `mcp__claw-drive__send_turn` with message `'API recovered. Retry the last operation.'` to trigger self-healing.
+        - None of the above → the session is still working; continue waiting; do NOT auto-kill.
+        - **Per-session idle > 30 min** (no `idle` event received, wall-clock elapsed) → surface to user for inspection; do NOT auto-kill.
+
+      - **`tool_decision_required`** → let the walker policy decide (auto-approve per rules, defer to user for anything not covered).
+
+      - **`turn_completed [DONE]`** → the session has finished its current turn with a `[DONE]` terminal token. If the on-disk task status is `final-gate` or `automated-gates`, push onto the final-gate queue. Otherwise continue monitoring.
+
+      - **`turn_completed [NEEDS-INPUT]`** → the session is paused waiting for a user reply. Surface the assistant's last message to the driver and send the user's response via `mcp__claw-drive__send_turn`.
+
+      - **`session_stopped`** → reconcile as in step 4.
 
-      - **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.
-      - **idle** (`silent_for_ms >= 600000`) → the session has been silent for 10 minutes. For each child session emitting this event, check whether it has reached a terminal state:
-        ```bash
-        claw-drive status <child_session_id>
-        ```
-        Read `last_token` from the status response. If `last_token` is `[DONE]` **or** the on-disk task status (`.cloverleaf/tasks/<TASK-ID>.json`) is `final-gate` or `automated-gates`, treat the session as terminal and proceed with drain (same as `session_stopped` → stopped cleanly). If neither condition is met, surface to the user for inspection; do NOT auto-kill.
-      - **Per-session idle > 30 min** (no `idle` event received, wall-clock elapsed) → surface to user for inspection; do NOT auto-kill.
+
+      **Transient-5xx self-healing.** Whenever any event's content (assistant text, error field, or status output) matches the pattern `5\d\d\b|API Error: 5\d\d|temporarily unavailable`, invoke:
+      ```
+      mcp__claw-drive__send_turn(session_id: <session_id>, text: "API recovered. Retry the last operation.")
+      ```
+      This covers transient API errors (e.g. HTTP 503, `API Error: 503`) and the `temporarily unavailable` service message without requiring a Session A nudge from the human.
 
    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:
 

package/lib/release-preflight.ts

@@ -1,172 +0,0 @@
-import { execSync } from 'node:child_process';
-import { readFileSync, existsSync } from 'node:fs';
-import { join } from 'node:path';
-
-export type CheckLevel = 'blocking' | 'warning';
-export type CheckStatus = 'pass' | 'fail';
-
-export interface PreflightCheck {
-  id: string;
-  level: CheckLevel;
-  status: CheckStatus;
-  message: string;
-}
-
-export interface PreflightResult {
-  checks: PreflightCheck[];
-  version: string;
-  tag: string;
-  notes: string;
-}
-
-function shell(cmd: string, cwd: string): { out: string; ok: boolean } {
-  try {
-    const out = execSync(cmd, { cwd, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
-    return { out: out.trim(), ok: true };
-  } catch (err: unknown) {
-    const e = err as { stdout?: string; stderr?: string; message?: string };
-    const msg = (e.stderr ?? e.stdout ?? e.message ?? String(err)).trim();
-    return { out: msg, ok: false };
-  }
-}
-
-/**
- * Run all pre-flight checks for a release from the given repo root.
- * Never throws — all errors are captured into per-check `message` fields.
- */
-export function runPreflightChecks(repoRoot: string): PreflightResult {
-  const checks: PreflightCheck[] = [];
-
-  // Helper to add a check result
-  function addCheck(
-    id: string,
-    level: CheckLevel,
-    pass: boolean,
-    failMsg: string,
-    passMsg = 'ok',
-  ): void {
-    checks.push({ id, level, status: pass ? 'pass' : 'fail', message: pass ? passMsg : failMsg });
-  }
-
-  // ── Blocking checks ────────────────────────────────────────────────────────
-
-  // 1. on-main: current branch must be main
-  const branch = shell('git rev-parse --abbrev-ref HEAD', repoRoot);
-  const isOnMain = branch.ok && branch.out === 'main';
-  addCheck('on-main', 'blocking', isOnMain, `not on main (current: ${branch.out})`);
-
-  // 2. clean-tree: no uncommitted changes
-  const status = shell('git status --porcelain', repoRoot);
-  const isClean = status.ok && status.out === '';
-  addCheck('clean-tree', 'blocking', isClean, `working tree is dirty: ${status.out || status.out}`);
-
-  // 3. in-sync-with-origin: no commits behind origin/main
-  // Fetch quietly first so we can compare
-  shell('git fetch origin main --quiet', repoRoot);
-  const behind = shell('git rev-list --count HEAD..origin/main', repoRoot);
-  const isSynced = behind.ok && behind.out === '0';
-  addCheck(
-    'in-sync-with-origin',
-    'blocking',
-    isSynced,
-    behind.ok ? `${behind.out} commit(s) behind origin/main` : `could not check sync: ${behind.out}`,
-  );
-
-  // 4. valid-version: reference-impl/package.json has a valid semver
-  let version = '';
-  try {
-    const pkgPath = join(repoRoot, 'reference-impl', 'package.json');
-    const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8')) as { version?: string };
-    version = pkg.version ?? '';
-  } catch (e: unknown) {
-    const msg = e instanceof Error ? e.message : String(e);
-    addCheck('valid-version', 'blocking', false, `could not read package.json: ${msg}`);
-    version = '';
-  }
-  if (version !== '') {
-    const semverRe = /^\d+\.\d+\.\d+(-[\w.]+)?(\+[\w.]+)?$/;
-    const isValidSemver = semverRe.test(version);
-    addCheck('valid-version', 'blocking', isValidSemver, `invalid semver: '${version}'`, `${version}`);
-  }
-
-  // 5. changelog-section: CHANGELOG.md has a section for this version
-  const tag = version ? `reference-impl-v${version}` : 'reference-impl-v<unknown>';
-  let changelogPass = false;
-  let changelogMsg = 'no version resolved';
-  if (version) {
-    try {
-      const changelogPath = join(repoRoot, 'reference-impl', 'CHANGELOG.md');
-      const changelog = readFileSync(changelogPath, 'utf-8');
-      // Look for a heading like "## 0.6.5" or "## [0.6.5]"
-      const pattern = new RegExp(`^##\\s+\\[?${version.replace(/\./g, '\\.')}`, 'm');
-      changelogPass = pattern.test(changelog);
-      changelogMsg = changelogPass
-        ? `section for ${version} found`
-        : `no ## ${version} section found in CHANGELOG.md`;
-    } catch (e: unknown) {
-      const msg = e instanceof Error ? e.message : String(e);
-      changelogMsg = `could not read CHANGELOG.md: ${msg}`;
-    }
-  }
-  addCheck('changelog-section', 'blocking', changelogPass, changelogMsg, changelogMsg);
-
-  // 6. tag-absent: the release tag must not already exist
-  let tagAbsent = false;
-  let tagMsg = 'no version resolved';
-  if (version) {
-    const localTag = shell(`git tag -l "${tag}"`, repoRoot);
-    const remoteTag = shell(`git ls-remote --tags origin "${tag}"`, repoRoot);
-    const existsLocally = localTag.ok && localTag.out !== '';
-    const existsRemotely = remoteTag.ok && remoteTag.out !== '';
-    tagAbsent = !existsLocally && !existsRemotely;
-    if (existsLocally && existsRemotely) {
-      tagMsg = `tag ${tag} already exists locally and on origin`;
-    } else if (existsLocally) {
-      tagMsg = `tag ${tag} already exists locally`;
-    } else if (existsRemotely) {
-      tagMsg = `tag ${tag} already exists on origin`;
-    } else {
-      tagMsg = `tag ${tag} is absent (ok)`;
-    }
-  }
-  addCheck('tag-absent', 'blocking', tagAbsent, tagMsg, tagMsg);
-
-  // ── Warning checks ─────────────────────────────────────────────────────────
-
-  // 7. npm-authenticated: `npm whoami` must exit 0
-  const npmAuth = shell('npm whoami', repoRoot);
-  addCheck(
-    'npm-authenticated',
-    'warning',
-    npmAuth.ok,
-    `npm not authenticated: ${npmAuth.out}`,
-    `logged in as ${npmAuth.out}`,
-  );
-
-  // 8. gh-authenticated: `gh auth status` must exit 0
-  const ghAuth = shell('gh auth status', repoRoot);
-  addCheck(
-    'gh-authenticated',
-    'warning',
-    ghAuth.ok,
-    `gh not authenticated: ${ghAuth.out}`,
-    'gh CLI authenticated',
-  );
-
-  // Derive release notes from CHANGELOG section
-  let notes = '';
-  if (version) {
-    try {
-      const changelogPath = join(repoRoot, 'reference-impl', 'CHANGELOG.md');
-      const changelog = readFileSync(changelogPath, 'utf-8');
-      const versionRegex = new RegExp(`^##\\s+\\[?${version.replace(/\./g, '\\.')}`, 'm');
-      const sections = changelog.split(/\n(?=## )/);
-      const match = sections.find((s) => versionRegex.test(s));
-      notes = match ? match.replace(/^[^\n]*\n/, '').trim() : '';
-    } catch {
-      notes = '';
-    }
-  }
-
-  return { checks, version, tag, notes };
-}

package/skills/cloverleaf-release/SKILL.md

@@ -1,109 +0,0 @@
----
-name: cloverleaf-release
-description: Publish a new @cloverleaf/reference-impl release. Runs pre-flight checks, displays the 5-command release plan, and executes git tag -a / git push origin main / git push origin <tag> / npm publish / gh release create. Accepts [--dry-run] [--yes] flags.
----
-
-# Cloverleaf — release
-
-The user has invoked this skill, optionally with `--dry-run` and/or `--yes`.
-
-## Args
-
-- `--dry-run` — print the pre-flight check list and the 5-command release plan, then exit 0 without executing any release command.
-- `--yes` — skip the interactive `y/N` prompt and execute the 5 commands unattended.
-
-## Steps
-
-1. **Parse flags.** Extract `--dry-run` and `--yes` from the invocation arguments if present.
-
-2. **Capture the repo root.**
-
-   ```bash
-   REPO_ROOT=$(git rev-parse --show-toplevel)
-   ```
-
-3. **Run pre-flight checks.**
-
-   ```bash
-   PREFLIGHT=$(cloverleaf-cli release-preflight "$REPO_ROOT" --json)
-   ```
-
-   Parse the JSON. Extract `version`, `tag`, and `notes`.
-
-4. **Display pre-flight check list.** For each check in `checks[]`:
-
-   - Status `pass` → prefix `✓`
-   - Status `fail` and level `warning` → prefix `⚠`
-   - Status `fail` and level `blocking` → prefix `✗`
-
-   Print one line per check: `<prefix> <id>: <message>`
-
-5. **Bail on any blocking failure.**
-
-   If any check has `level === "blocking"` and `status === "fail"`, print:
-
-   ```
-   ✗ Pre-flight failed — fix the issues above before releasing.
-   ```
-
-   And exit 1.
-
-6. **Display release plan.**
-
-   Print:
-
-   ```
-   Release plan for <tag>:
-     1. git tag -a <tag> -m "Release <tag>"
-     2. git push origin main
-     3. git push origin <tag>
-     4. cd reference-impl && npm publish --access public
-     5. gh release create <tag> --notes-file /tmp/release-notes-$VERSION.md
-
-   Version: <version>
-   Notes preview:
-   <notes (first 10 lines or "(no notes)" if empty)>
-   ```
-
-7. **If `--dry-run`:** Print `Dry run complete — no release commands executed.` and exit 0.
-
-8. **If not `--yes`:** Prompt:
-
-   ```
-   Proceed with release of <tag>? (y/N)
-   ```
-
-   Read a single line from the user. If the response is not `y` or `Y`, print `Aborted.` and exit 0.
-
-9. **Write the release notes file.**
-
-   ```bash
-   VERSION=<version>
-   printf '%s' "$NOTES" > /tmp/release-notes-$VERSION.md
-   ```
-
-10. **Execute the 5 release commands sequentially, bail-fast on first non-zero exit.**
-
-    ```bash
-    git tag -a "reference-impl-v$VERSION" -m "Release reference-impl-v$VERSION"
-    git push origin main
-    git push origin "reference-impl-v$VERSION"
-    cd reference-impl && npm publish --access public
-    gh release create "reference-impl-v$VERSION" --notes-file "/tmp/release-notes-$VERSION.md"
-    ```
-
-    If any command fails, print `✗ Release failed at step N: <command>` and exit 1.
-
-11. **Report success.**
-
-    ```
-    ✓ Released reference-impl-v<version>
-    ```
-
-## Rules
-
-- Never skip pre-flight checks, even with `--yes`.
-- Warning-level check failures (`⚠`) do not block execution — they are informational only.
-- Do NOT modify `.cloverleaf/` — this skill only releases, it does not change task state.
-- The skill's working directory is the consumer's repo root.
-- Do not use hardcoded plugin paths — use `cloverleaf-cli` for all CLI invocations.