@cloverleaf/reference-impl 0.6.7 → 0.7.1

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. `lib/scope-check.ts` exports `classifyFiles(taskDoc, modifiedFiles, siblingScopes)` — classifies branch-modified files into `own`, `contested`, and `extension` buckets; exposed via `cloverleaf-cli check-scope <repoRoot> <taskId> --branch <branchName>` (prints JSON, exits 1 on missing branch/task doc) and `cloverleaf-cli extend-scope <repoRoot> <taskId> --add <file>... --reason <text>` (idempotently set-unions files into `scope.files_touched` and appends an audit entry to `.cloverleaf/runs/plan/<PLAN-ID>/audit.jsonl`).
 - `skills/` — Claude Code skill markdown files.
 - `prompts/` — Implementer/Reviewer subagent system prompts.
 - `examples/toy-repo/` — standalone demo repo.

package/dist/cli.mjs

@@ -35,11 +35,13 @@
  *   walk-state-read <repoRoot> <planId>
  *   walk-state-write <repoRoot> <walkStateJsonPath>
  *   walker-default-concurrency [--explain]
+ *   check-scope <repoRoot> <taskId> --branch <branchName>
+ *   extend-scope <repoRoot> <taskId> --add <file>... --reason <text>
  */
-import { readFileSync, mkdirSync, copyFileSync } from 'node:fs';
-import { dirname } from 'node:path';
+import { readFileSync, mkdirSync, copyFileSync, appendFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
 import { execSync } from 'node:child_process';
-import { loadTask } from './task.mjs';
+import { loadTask, saveTask } from './task.mjs';
 import { advanceStatus } from './task.mjs';
 import { emitGateDecision } from './events.mjs';
 import { writeFeedback, latestFeedback } from './feedback.mjs';
@@ -60,6 +62,7 @@ import { buildBaselinePath } from './visual-diff.mjs';
 import { computeReadyTasks, detectCycle } from './dag-walker.mjs';
 import { readWalkState, writeWalkState, walkStatePath } from './walk-state.mjs';
 import { loadWalkerConfig } from './walker-config.mjs';
+import { classifyFiles } from './scope-check.mjs';
 function die(msg, code = 1) {
     process.stderr.write(msg + '\n');
     process.exit(code);
@@ -98,7 +101,9 @@ function usage(msg) {
         '  dag-detect-cycle <repoRoot> <planId>\n' +
         '  walk-state-read <repoRoot> <planId>\n' +
         '  walk-state-write <repoRoot> <walkStateJsonPath>\n' +
-        '  walker-default-concurrency [--explain]\n');
+        '  walker-default-concurrency [--explain]\n' +
+        '  check-scope <repoRoot> <taskId> --branch <branchName>\n' +
+        '  extend-scope <repoRoot> <taskId> --add <file>... --reason <text>\n');
     process.exit(2);
 }
 const [, , command, ...rest] = process.argv;
@@ -523,6 +528,176 @@ try {
             }
             process.exit(0);
         }
+        case 'check-scope': {
+            // check-scope <repoRoot> <taskId> --branch <branchName>
+            const positional = rest.filter((a) => !a.startsWith('--'));
+            const flags = rest.filter((a) => a.startsWith('--'));
+            const [repoRoot, taskId] = positional;
+            if (!repoRoot || !taskId)
+                usage('check-scope requires <repoRoot> <taskId> --branch <branchName>');
+            const branchFlag = flags.find((f) => f === '--branch');
+            const branchIdx = rest.indexOf('--branch');
+            const branchName = branchFlag !== undefined && branchIdx >= 0 ? rest[branchIdx + 1] : undefined;
+            if (!branchName) {
+                process.stderr.write('check-scope: missing --branch <branchName>\n');
+                process.exit(2);
+            }
+            // 1. Read task doc from feature branch via git show
+            let taskDoc;
+            try {
+                const taskPath = `.cloverleaf/tasks/${taskId}.json`;
+                const raw = execSync(`git show ${branchName}:${taskPath}`, {
+                    cwd: repoRoot,
+                    encoding: 'utf-8',
+                    stdio: ['pipe', 'pipe', 'pipe'],
+                });
+                taskDoc = JSON.parse(raw);
+            }
+            catch {
+                try {
+                    // Fall back to checking if the branch exists at all
+                    execSync(`git rev-parse --verify ${branchName}`, {
+                        cwd: repoRoot,
+                        encoding: 'utf-8',
+                        stdio: ['pipe', 'pipe', 'pipe'],
+                    });
+                    // Branch exists but no task doc
+                    process.stderr.write(`check-scope: task doc not found for ${taskId} on branch ${branchName}\n`);
+                }
+                catch {
+                    process.stderr.write(`check-scope: branch ${branchName} not found\n`);
+                }
+                process.exit(1);
+            }
+            // 2. Read sibling scopes from main
+            const siblingScopes = [];
+            try {
+                // List all task files visible on main
+                const lsOut = execSync(`git ls-tree -r --name-only main -- .cloverleaf/tasks/`, {
+                    cwd: repoRoot,
+                    encoding: 'utf-8',
+                    stdio: ['pipe', 'pipe', 'pipe'],
+                });
+                const taskFiles = lsOut.split('\n').map((l) => l.trim()).filter(Boolean);
+                for (const f of taskFiles) {
+                    const tid = f.replace(/^\.cloverleaf\/tasks\//, '').replace(/\.json$/, '');
+                    if (tid === taskId)
+                        continue; // skip self
+                    try {
+                        const raw = execSync(`git show main:${f}`, {
+                            cwd: repoRoot,
+                            encoding: 'utf-8',
+                            stdio: ['pipe', 'pipe', 'pipe'],
+                        });
+                        const sibling = JSON.parse(raw);
+                        const scope = sibling['scope'];
+                        const files = Array.isArray(scope?.['files_touched'])
+                            ? scope['files_touched'].filter((x) => typeof x === 'string')
+                            : [];
+                        if (files.length > 0) {
+                            siblingScopes.push({ taskId: tid, files });
+                        }
+                    }
+                    catch {
+                        // Skip task files that can't be read
+                    }
+                }
+            }
+            catch {
+                // main may not exist yet; treat as no siblings
+            }
+            // 3. Get modified files via git diff main..<branch>
+            let modifiedFiles = [];
+            try {
+                const diffOut = execSync(`git diff --name-only main..${branchName}`, {
+                    cwd: repoRoot,
+                    encoding: 'utf-8',
+                    stdio: ['pipe', 'pipe', 'pipe'],
+                });
+                modifiedFiles = diffOut.split('\n').map((l) => l.trim()).filter(Boolean);
+            }
+            catch {
+                // No diff is fine (empty branch)
+            }
+            // 4. Classify and output
+            const result = classifyFiles(taskDoc, modifiedFiles, siblingScopes);
+            process.stdout.write(JSON.stringify(result) + '\n');
+            process.exit(0);
+        }
+        case 'extend-scope': {
+            // extend-scope <repoRoot> <taskId> --add <file>... --reason <text>
+            const positional = rest.filter((a) => !a.startsWith('--'));
+            const [repoRoot, taskId] = positional;
+            if (!repoRoot || !taskId)
+                usage('extend-scope requires <repoRoot> <taskId> --add <file>... --reason <text>');
+            // Parse --reason (takes everything after --reason up to another flag)
+            const reasonIdx = rest.indexOf('--reason');
+            if (reasonIdx < 0 || !rest[reasonIdx + 1]) {
+                process.stderr.write('extend-scope: missing --reason <text>\n');
+                process.exit(2);
+            }
+            // Collect reason: everything after --reason that doesn't start with --
+            const reasonParts = [];
+            for (let i = reasonIdx + 1; i < rest.length; i++) {
+                if (rest[i].startsWith('--'))
+                    break;
+                reasonParts.push(rest[i]);
+            }
+            const reason = reasonParts.join(' ');
+            if (!reason) {
+                process.stderr.write('extend-scope: --reason requires a non-empty value\n');
+                process.exit(2);
+            }
+            // Parse --add <file>... (all values after --add that don't start with --)
+            const addIdx = rest.indexOf('--add');
+            if (addIdx < 0) {
+                process.stderr.write('extend-scope: missing --add <file>...\n');
+                process.exit(2);
+            }
+            const addFiles = [];
+            for (let i = addIdx + 1; i < rest.length; i++) {
+                if (rest[i].startsWith('--'))
+                    break;
+                addFiles.push(rest[i]);
+            }
+            if (addFiles.length === 0) {
+                process.stderr.write('extend-scope: --add requires at least one file\n');
+                process.exit(2);
+            }
+            // Load task doc
+            const task = loadTask(repoRoot, taskId);
+            // Get current scope.files_touched
+            const scope = (task['scope'] ?? {});
+            const currentFiles = Array.isArray(scope['files_touched'])
+                ? scope['files_touched'].filter((f) => typeof f === 'string')
+                : [];
+            // Set-union and sort/dedup
+            const merged = Array.from(new Set([...currentFiles, ...addFiles])).sort();
+            // Check if idempotent (no change needed)
+            const newlyAdded = addFiles.filter((f) => !currentFiles.includes(f));
+            // Always update and save (even if idempotent, shape is canonical)
+            const updatedTask = {
+                ...task,
+                scope: { ...scope, files_touched: merged },
+            };
+            saveTask(repoRoot, updatedTask);
+            // Append audit entry
+            // Find plan ID from task.parent or task.context
+            const parent = task['parent'];
+            const planId = parent?.id ?? taskId; // fallback to taskId if no parent
+            const auditDir = join(repoRoot, '.cloverleaf', 'runs', 'plan', planId);
+            mkdirSync(auditDir, { recursive: true });
+            const auditPath = join(auditDir, 'audit.jsonl');
+            const auditEntry = {
+                ts: new Date().toISOString(),
+                kind: 'extend-scope',
+                task_id: taskId,
+                files: newlyAdded,
+                reason,
+            };
+            appendFileSync(auditPath, JSON.stringify(auditEntry) + '\n');
+            process.exit(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/dist/scope-check.mjs

@@ -0,0 +1,133 @@
+/**
+ * scope-check.ts — reference-impl v0.7.0
+ *
+ * Classifies a task's modified files into three buckets:
+ *  - own: file is declared in the task's own scope.files_touched
+ *  - contested: file is declared by a sibling task in the same Plan
+ *  - extension: file was touched but not declared by anyone
+ *
+ * Algorithm:
+ *  1. Normalize all input paths (taskDoc.scope.files_touched, modifiedFiles,
+ *     every siblingScopes[*].files) using the same rules as dag-overlap.ts:
+ *     trim, replace backslashes, strip leading `./`, strip trailing `/`.
+ *     Drop empties after normalization.
+ *  2. Build:
+ *     - ownSet = normalized set of taskDoc.scope?.files_touched ?? []
+ *     - siblingMap = Map<normalizedFile, sortedListOfTaskIds> from all siblings
+ *       (a single file may be claimed by multiple siblings — kept sorted lex ascending)
+ *  3. Filter out any modified file whose normalized path starts with `.cloverleaf/`
+ *     (these are state-machine transitions, not work).
+ *  4. For each remaining normalized modified file f (in input order, deduped):
+ *     - If f ∈ ownSet → push to own
+ *     - Else if siblingMap.has(f) → push { file: f, owner: siblingMap.get(f)![0] } to contested
+ *       (lex-smallest sibling id wins)
+ *     - Else → push to extension
+ *  5. Sort all three output bucket arrays lexicographically by file path.
+ *  6. Return { contested, own, extension }.
+ *
+ * Exact-path comparison only — no glob expansion (mirrors dag-overlap.ts v0.7.0 non-goals).
+ */
+/**
+ * Normalize a raw file path from `scope.files_touched` or modifiedFiles.
+ *
+ * Rules (applied in order):
+ *  - Trim whitespace
+ *  - Replace backslashes with forward-slashes
+ *  - Strip any number of leading `./` sequences
+ *  - Strip trailing `/` (preserving a non-empty result)
+ *  - 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;
+}
+/**
+ * Normalize an array of paths and drop empty strings after normalization.
+ */
+function normalizePaths(paths) {
+    const result = [];
+    for (const p of paths) {
+        if (typeof p !== 'string')
+            continue;
+        const n = normalizePath(p);
+        if (n.length > 0)
+            result.push(n);
+    }
+    return result;
+}
+/**
+ * Classify a task's modified files into own, contested, and extension buckets.
+ *
+ * @param taskDoc       - The task document whose scope declares "own" files.
+ * @param modifiedFiles - The list of files actually modified (e.g., from git diff).
+ * @param siblingScopes - Other tasks in the same Plan with their declared files.
+ * @returns             - { contested, own, extension } with arrays sorted by file path.
+ */
+export function classifyFiles(taskDoc, modifiedFiles, siblingScopes) {
+    // 1. Normalize own files from taskDoc.scope.files_touched
+    const scope = taskDoc['scope'];
+    const rawOwn = Array.isArray(scope?.['files_touched'])
+        ? scope['files_touched'].filter((f) => typeof f === 'string')
+        : [];
+    const ownSet = new Set(normalizePaths(rawOwn));
+    // 2. Build siblingMap: normalizedFile → sorted list of taskIds
+    const siblingMap = new Map();
+    for (const sibling of siblingScopes) {
+        const normalized = normalizePaths(sibling.files);
+        for (const f of normalized) {
+            const existing = siblingMap.get(f);
+            if (existing) {
+                existing.push(sibling.taskId);
+                existing.sort();
+            }
+            else {
+                siblingMap.set(f, [sibling.taskId]);
+            }
+        }
+    }
+    // 3. Normalize modifiedFiles, filter .cloverleaf/ prefix, deduplicate
+    const seen = new Set();
+    const filteredModified = [];
+    for (const raw of modifiedFiles) {
+        if (typeof raw !== 'string')
+            continue;
+        const n = normalizePath(raw);
+        if (n.length === 0)
+            continue;
+        if (n.startsWith('.cloverleaf/'))
+            continue;
+        if (seen.has(n))
+            continue;
+        seen.add(n);
+        filteredModified.push(n);
+    }
+    // 4. Classify each file into the appropriate bucket
+    const own = [];
+    const contested = [];
+    const extension = [];
+    for (const f of filteredModified) {
+        if (ownSet.has(f)) {
+            own.push(f);
+        }
+        else if (siblingMap.has(f)) {
+            const owners = siblingMap.get(f);
+            contested.push({ file: f, owner: owners[0] }); // lex-smallest wins
+        }
+        else {
+            extension.push(f);
+        }
+    }
+    // 5. Sort all buckets lexicographically by file path
+    own.sort();
+    contested.sort((a, b) => a.file.localeCompare(b.file));
+    extension.sort();
+    return { contested, own, extension };
+}

package/lib/cli.ts

@@ -35,12 +35,14 @@
  *   walk-state-read <repoRoot> <planId>
  *   walk-state-write <repoRoot> <walkStateJsonPath>
  *   walker-default-concurrency [--explain]
+ *   check-scope <repoRoot> <taskId> --branch <branchName>
+ *   extend-scope <repoRoot> <taskId> --add <file>... --reason <text>
  */
 
-import { readFileSync, mkdirSync, copyFileSync } from 'node:fs';
-import { dirname } from 'node:path';
+import { readFileSync, mkdirSync, copyFileSync, appendFileSync, existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
 import { execSync } from 'node:child_process';
-import { loadTask } from './task.js';
+import { loadTask, saveTask } from './task.js';
 import { advanceStatus } from './task.js';
 import { emitGateDecision } from './events.js';
 import { writeFeedback, latestFeedback } from './feedback.js';
@@ -62,6 +64,8 @@ import { buildBaselinePath } from './visual-diff.js';
 import { computeReadyTasks, detectCycle } from './dag-walker.js';
 import { readWalkState, writeWalkState, walkStatePath } from './walk-state.js';
 import { loadWalkerConfig } from './walker-config.js';
+import { classifyFiles } from './scope-check.js';
+import type { SiblingScope } from './scope-check.js';
 
 function die(msg: string, code = 1): never {
   process.stderr.write(msg + '\n');
@@ -102,7 +106,9 @@ function usage(msg?: string): never {
       '  dag-detect-cycle <repoRoot> <planId>\n' +
       '  walk-state-read <repoRoot> <planId>\n' +
       '  walk-state-write <repoRoot> <walkStateJsonPath>\n' +
-      '  walker-default-concurrency [--explain]\n'
+      '  walker-default-concurrency [--explain]\n' +
+      '  check-scope <repoRoot> <taskId> --branch <branchName>\n' +
+      '  extend-scope <repoRoot> <taskId> --add <file>... --reason <text>\n'
   );
   process.exit(2);
 }
@@ -537,6 +543,184 @@ try {
       process.exit(0);
     }
 
+    case 'check-scope': {
+      // check-scope <repoRoot> <taskId> --branch <branchName>
+      const positional = rest.filter((a) => !a.startsWith('--'));
+      const flags = rest.filter((a) => a.startsWith('--'));
+      const [repoRoot, taskId] = positional;
+      if (!repoRoot || !taskId) usage('check-scope requires <repoRoot> <taskId> --branch <branchName>');
+
+      const branchFlag = flags.find((f) => f === '--branch');
+      const branchIdx = rest.indexOf('--branch');
+      const branchName = branchFlag !== undefined && branchIdx >= 0 ? rest[branchIdx + 1] : undefined;
+      if (!branchName) {
+        process.stderr.write('check-scope: missing --branch <branchName>\n');
+        process.exit(2);
+      }
+
+      // 1. Read task doc from feature branch via git show
+      let taskDoc: ReturnType<typeof loadTask>;
+      try {
+        const taskPath = `.cloverleaf/tasks/${taskId}.json`;
+        const raw = execSync(`git show ${branchName}:${taskPath}`, {
+          cwd: repoRoot,
+          encoding: 'utf-8',
+          stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        taskDoc = JSON.parse(raw) as ReturnType<typeof loadTask>;
+      } catch {
+        try {
+          // Fall back to checking if the branch exists at all
+          execSync(`git rev-parse --verify ${branchName}`, {
+            cwd: repoRoot,
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+          });
+          // Branch exists but no task doc
+          process.stderr.write(`check-scope: task doc not found for ${taskId} on branch ${branchName}\n`);
+        } catch {
+          process.stderr.write(`check-scope: branch ${branchName} not found\n`);
+        }
+        process.exit(1);
+      }
+
+      // 2. Read sibling scopes from main
+      const siblingScopes: SiblingScope[] = [];
+      try {
+        // List all task files visible on main
+        const lsOut = execSync(`git ls-tree -r --name-only main -- .cloverleaf/tasks/`, {
+          cwd: repoRoot,
+          encoding: 'utf-8',
+          stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        const taskFiles = lsOut.split('\n').map((l) => l.trim()).filter(Boolean);
+        for (const f of taskFiles) {
+          const tid = f.replace(/^\.cloverleaf\/tasks\//, '').replace(/\.json$/, '');
+          if (tid === taskId) continue; // skip self
+          try {
+            const raw = execSync(`git show main:${f}`, {
+              cwd: repoRoot,
+              encoding: 'utf-8',
+              stdio: ['pipe', 'pipe', 'pipe'],
+            });
+            const sibling = JSON.parse(raw) as Record<string, unknown>;
+            const scope = sibling['scope'] as Record<string, unknown> | undefined;
+            const files = Array.isArray(scope?.['files_touched'])
+              ? (scope!['files_touched'] as unknown[]).filter((x): x is string => typeof x === 'string')
+              : [];
+            if (files.length > 0) {
+              siblingScopes.push({ taskId: tid, files });
+            }
+          } catch {
+            // Skip task files that can't be read
+          }
+        }
+      } catch {
+        // main may not exist yet; treat as no siblings
+      }
+
+      // 3. Get modified files via git diff main..<branch>
+      let modifiedFiles: string[] = [];
+      try {
+        const diffOut = execSync(`git diff --name-only main..${branchName}`, {
+          cwd: repoRoot,
+          encoding: 'utf-8',
+          stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        modifiedFiles = diffOut.split('\n').map((l) => l.trim()).filter(Boolean);
+      } catch {
+        // No diff is fine (empty branch)
+      }
+
+      // 4. Classify and output
+      const result = classifyFiles(taskDoc, modifiedFiles, siblingScopes);
+      process.stdout.write(JSON.stringify(result) + '\n');
+      process.exit(0);
+    }
+
+    case 'extend-scope': {
+      // extend-scope <repoRoot> <taskId> --add <file>... --reason <text>
+      const positional = rest.filter((a) => !a.startsWith('--'));
+      const [repoRoot, taskId] = positional;
+      if (!repoRoot || !taskId) usage('extend-scope requires <repoRoot> <taskId> --add <file>... --reason <text>');
+
+      // Parse --reason (takes everything after --reason up to another flag)
+      const reasonIdx = rest.indexOf('--reason');
+      if (reasonIdx < 0 || !rest[reasonIdx + 1]) {
+        process.stderr.write('extend-scope: missing --reason <text>\n');
+        process.exit(2);
+      }
+      // Collect reason: everything after --reason that doesn't start with --
+      const reasonParts: string[] = [];
+      for (let i = reasonIdx + 1; i < rest.length; i++) {
+        if (rest[i].startsWith('--')) break;
+        reasonParts.push(rest[i]);
+      }
+      const reason = reasonParts.join(' ');
+      if (!reason) {
+        process.stderr.write('extend-scope: --reason requires a non-empty value\n');
+        process.exit(2);
+      }
+
+      // Parse --add <file>... (all values after --add that don't start with --)
+      const addIdx = rest.indexOf('--add');
+      if (addIdx < 0) {
+        process.stderr.write('extend-scope: missing --add <file>...\n');
+        process.exit(2);
+      }
+      const addFiles: string[] = [];
+      for (let i = addIdx + 1; i < rest.length; i++) {
+        if (rest[i].startsWith('--')) break;
+        addFiles.push(rest[i]);
+      }
+      if (addFiles.length === 0) {
+        process.stderr.write('extend-scope: --add requires at least one file\n');
+        process.exit(2);
+      }
+
+      // Load task doc
+      const task = loadTask(repoRoot, taskId);
+
+      // Get current scope.files_touched
+      const scope = (task['scope'] ?? {}) as Record<string, unknown>;
+      const currentFiles = Array.isArray(scope['files_touched'])
+        ? (scope['files_touched'] as unknown[]).filter((f): f is string => typeof f === 'string')
+        : [];
+
+      // Set-union and sort/dedup
+      const merged = Array.from(new Set([...currentFiles, ...addFiles])).sort();
+
+      // Check if idempotent (no change needed)
+      const newlyAdded = addFiles.filter((f) => !currentFiles.includes(f));
+
+      // Always update and save (even if idempotent, shape is canonical)
+      const updatedTask = {
+        ...task,
+        scope: { ...scope, files_touched: merged },
+      };
+      saveTask(repoRoot, updatedTask);
+
+      // Append audit entry
+      // Find plan ID from task.parent or task.context
+      const parent = task['parent'] as { project?: string; id?: string } | undefined;
+      const planId = parent?.id ?? taskId; // fallback to taskId if no parent
+
+      const auditDir = join(repoRoot, '.cloverleaf', 'runs', 'plan', planId);
+      mkdirSync(auditDir, { recursive: true });
+      const auditPath = join(auditDir, 'audit.jsonl');
+
+      const auditEntry = {
+        ts: new Date().toISOString(),
+        kind: 'extend-scope',
+        task_id: taskId,
+        files: newlyAdded,
+        reason,
+      };
+      appendFileSync(auditPath, JSON.stringify(auditEntry) + '\n');
+
+      process.exit(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/lib/scope-check.ts

@@ -0,0 +1,155 @@
+/**
+ * scope-check.ts — reference-impl v0.7.0
+ *
+ * Classifies a task's modified files into three buckets:
+ *  - own: file is declared in the task's own scope.files_touched
+ *  - contested: file is declared by a sibling task in the same Plan
+ *  - extension: file was touched but not declared by anyone
+ *
+ * Algorithm:
+ *  1. Normalize all input paths (taskDoc.scope.files_touched, modifiedFiles,
+ *     every siblingScopes[*].files) using the same rules as dag-overlap.ts:
+ *     trim, replace backslashes, strip leading `./`, strip trailing `/`.
+ *     Drop empties after normalization.
+ *  2. Build:
+ *     - ownSet = normalized set of taskDoc.scope?.files_touched ?? []
+ *     - siblingMap = Map<normalizedFile, sortedListOfTaskIds> from all siblings
+ *       (a single file may be claimed by multiple siblings — kept sorted lex ascending)
+ *  3. Filter out any modified file whose normalized path starts with `.cloverleaf/`
+ *     (these are state-machine transitions, not work).
+ *  4. For each remaining normalized modified file f (in input order, deduped):
+ *     - If f ∈ ownSet → push to own
+ *     - Else if siblingMap.has(f) → push { file: f, owner: siblingMap.get(f)![0] } to contested
+ *       (lex-smallest sibling id wins)
+ *     - Else → push to extension
+ *  5. Sort all three output bucket arrays lexicographically by file path.
+ *  6. Return { contested, own, extension }.
+ *
+ * Exact-path comparison only — no glob expansion (mirrors dag-overlap.ts v0.7.0 non-goals).
+ */
+
+import type { TaskDoc } from './task.js';
+
+export interface ContestedEntry {
+  file: string;
+  owner: string;
+}
+
+export interface ClassifyResult {
+  contested: ContestedEntry[];
+  own: string[];
+  extension: string[];
+}
+
+export interface SiblingScope {
+  taskId: string;
+  files: string[];
+}
+
+/**
+ * Normalize a raw file path from `scope.files_touched` or modifiedFiles.
+ *
+ * Rules (applied in order):
+ *  - Trim whitespace
+ *  - Replace backslashes with forward-slashes
+ *  - Strip any number of leading `./` sequences
+ *  - Strip trailing `/` (preserving a non-empty result)
+ *  - 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;
+}
+
+/**
+ * Normalize an array of paths and drop empty strings after normalization.
+ */
+function normalizePaths(paths: string[]): string[] {
+  const result: string[] = [];
+  for (const p of paths) {
+    if (typeof p !== 'string') continue;
+    const n = normalizePath(p);
+    if (n.length > 0) result.push(n);
+  }
+  return result;
+}
+
+/**
+ * Classify a task's modified files into own, contested, and extension buckets.
+ *
+ * @param taskDoc       - The task document whose scope declares "own" files.
+ * @param modifiedFiles - The list of files actually modified (e.g., from git diff).
+ * @param siblingScopes - Other tasks in the same Plan with their declared files.
+ * @returns             - { contested, own, extension } with arrays sorted by file path.
+ */
+export function classifyFiles(
+  taskDoc: TaskDoc,
+  modifiedFiles: string[],
+  siblingScopes: SiblingScope[]
+): ClassifyResult {
+  // 1. Normalize own files from taskDoc.scope.files_touched
+  const scope = taskDoc['scope'] as Record<string, unknown> | undefined;
+  const rawOwn = Array.isArray(scope?.['files_touched'])
+    ? (scope!['files_touched'] as unknown[]).filter((f): f is string => typeof f === 'string')
+    : [];
+  const ownSet = new Set(normalizePaths(rawOwn));
+
+  // 2. Build siblingMap: normalizedFile → sorted list of taskIds
+  const siblingMap = new Map<string, string[]>();
+  for (const sibling of siblingScopes) {
+    const normalized = normalizePaths(sibling.files);
+    for (const f of normalized) {
+      const existing = siblingMap.get(f);
+      if (existing) {
+        existing.push(sibling.taskId);
+        existing.sort();
+      } else {
+        siblingMap.set(f, [sibling.taskId]);
+      }
+    }
+  }
+
+  // 3. Normalize modifiedFiles, filter .cloverleaf/ prefix, deduplicate
+  const seen = new Set<string>();
+  const filteredModified: string[] = [];
+  for (const raw of modifiedFiles) {
+    if (typeof raw !== 'string') continue;
+    const n = normalizePath(raw);
+    if (n.length === 0) continue;
+    if (n.startsWith('.cloverleaf/')) continue;
+    if (seen.has(n)) continue;
+    seen.add(n);
+    filteredModified.push(n);
+  }
+
+  // 4. Classify each file into the appropriate bucket
+  const own: string[] = [];
+  const contested: ContestedEntry[] = [];
+  const extension: string[] = [];
+
+  for (const f of filteredModified) {
+    if (ownSet.has(f)) {
+      own.push(f);
+    } else if (siblingMap.has(f)) {
+      const owners = siblingMap.get(f)!;
+      contested.push({ file: f, owner: owners[0] }); // lex-smallest wins
+    } else {
+      extension.push(f);
+    }
+  }
+
+  // 5. Sort all buckets lexicographically by file path
+  own.sort();
+  contested.sort((a, b) => a.file.localeCompare(b.file));
+  extension.sort();
+
+  return { contested, own, extension };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloverleaf/reference-impl",
-  "version": "0.6.7",
+  "version": "0.7.1",
   "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/implementer.md

@@ -20,6 +20,9 @@ You are the Cloverleaf Implementer agent. Your job: take a Task and produce work
    Run this as the first executable step before anything else. Session B sessions may inherit an arbitrary `cwd` from the walker harness; this anchors you at the repo root.
 
 1. Read the task's `title`, `acceptance_criteria`, `definition_of_done`, and `context`. Read any referenced files.
+
+   **Scope nudge.** Your declared scope is `task.scope.files_touched`. You may freely modify any file listed there. If you discover during implementation that you need to touch a file outside that list, you may do so only if no sibling task in the same Plan declares that file — the walker auto-extends your scope on merge. If a file you need is already declared by a sibling task, that is a contested modification: stop, surface the conflict to the human, and do not merge. The walker enforces this at merge time and will refuse contested merges; auto-resolution is never attempted.
+
 2. If `feedback` is present, re-read each finding; plan how to address them.
 3. Create a new branch named `cloverleaf/<task.id>` from `base_branch` using `git checkout -b cloverleaf/<task.id>`.
 4. Implement the code + tests needed to satisfy every acceptance criterion.

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

@@ -169,6 +169,27 @@ description: Autonomous DAG walker for Cloverleaf Plans. Given a PLAN-ID in stat
 
    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:
 
+      **Scope check (BEFORE the y/N prompt).** Run `cloverleaf-cli check-scope` and capture its output and exit code:
+
+      ```bash
+      SCOPE_JSON=$(cloverleaf-cli check-scope <repo_root> <TASK-ID> --branch cloverleaf/<TASK-ID> 2>/dev/null)
+      SCOPE_EXIT=$?
+      ```
+
+      - **If exit 0**: parse the JSON. If `contested[]` is non-empty:
+        - **Skip the y/N prompt entirely.**
+        - Mark the task `state: "escalated"` in walk-state via `walk-state-write`.
+        - Surface the following message to the driver (the literal contested-escalation message template):
+          ```
+          ⚠️ <TASK-ID> escalated: scope-contested merge. Files contested with sibling task(s): <list of file:owned_by pairs>. Walker will not auto-resolve. Inspect the Plan decomposition (CLV-86 vs CLV-87 etc.) and either (a) re-decompose so each contested file is owned by exactly one task, or (b) merge the colliding tasks into one. Re-run /cloverleaf-run-plan <PLAN-ID> after fixing.
+          ```
+        - Continue to the next queued task. Do NOT proceed to the merge prompt.
+      - **If exit non-zero (tooling failure)**: print a warning and fall through to the existing merge flow without scope enforcement (**warn-and-proceed**):
+        ```
+        ⚠️ check-scope failed (exit N) — falling through to existing merge flow without scope enforcement.
+        ```
+      - **If exit 0 and `contested[]` is empty**: proceed normally to the summary + y/N prompt below. Retain the parsed `extension[]` array from the JSON for use in the post-merge auto-extend block.
+
       1. Print a full summary to the driver:
          ```
          ⏵ <TASK-ID> ready to merge (<fast lane | full pipeline>)
@@ -221,6 +242,16 @@ description: Autonomous DAG walker for Cloverleaf Plans. Given a PLAN-ID in stat
          # The updated walk-state sets tasks["<TASK-ID>"].state = "merged"
          #                           and tasks["<TASK-ID>"].merge_commit = "$MERGE_COMMIT"
          ```
+         **Post-merge auto-extend.** If the `extension[]` array captured from the earlier `cloverleaf-cli check-scope` call was non-empty, invoke `extend-scope` and commit the amended task doc:
+
+         ```bash
+         cloverleaf-cli extend-scope <repo_root> <TASK-ID> --add <file1> --add <file2> ... --reason "auto-extended post-merge: files touched but undeclared"
+         git -C <repo_root> add .cloverleaf/tasks/<TASK-ID>.json .cloverleaf/runs/plan/<PLAN-ID>/audit.jsonl
+         git -C <repo_root> commit -m "cloverleaf: <TASK-ID> scope auto-extended (+N files)"
+         ```
+
+         where N is the count of files in `extension[]`.
+
          Send `y` (informational) back to Session B so it can record the outcome and exit, but the walker is the authoritative merge-performer.
          **Tear down the worktree**: `git -C <repo_root> worktree remove --force <worktree_path>`. Delete the branch is optional (keep if useful for post-hoc inspection).
       4. If it matches `^n(o)?$|^N(O)?$` → mark task `state: "awaiting_final_gate"`. Send `n` to Session B. **Keep the worktree** so the user can re-run `/cloverleaf-merge <TASK-ID>` manually pointing at it, or fix and retry. Continue with the next queued task.
@@ -310,3 +341,4 @@ The concrete policy JSON is the same one used during the CLV-16..CLV-20 dogfood
 - Escalations surface immediately; they do NOT queue behind the final-gate drain.
 - Final-gate drain is serial across tasks — one prompt, one decision.
 - The walker exits after the loop reports the final status; it does not auto-retry escalated tasks.
+- Scope-contested merges are escalated, never auto-resolved.