@cloverleaf/reference-impl 0.7.0 → 0.7.2

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/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/` — 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,179 @@ 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);
+                        // Skip siblings that are already merged — they no longer contest scope
+                        if (sibling['status'] === 'merged')
+                            continue;
+                        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/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,186 @@ 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>;
+            // Skip siblings that are already merged — they no longer contest scope
+            if (sibling['status'] === 'merged') continue;
+            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/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.7.0",
+  "version": "0.7.2",
   "description": "Reference implementation of the Cloverleaf methodology as Claude Code skills. Implements the Tight Loop (Implementer + Reviewer).",
   "type": "module",
   "license": "MIT",

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

@@ -89,3 +89,11 @@ Dependencies:
 **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.
+
+**Partial-scope warning:** Count the tasks where `scope.files_touched` is absent or an empty array. If that count is greater than zero, append the following warning line at the bottom of the gate-pending summary (substituting the actual task IDs), then add an advisory note that the walker will silent-skip scope enforcement on those tasks:
+
+```
+⚠ Tasks without scope.files_touched: <CLV-XX, CLV-YY>
+```
+
+Omit this warning line entirely when every task has a non-empty `scope.files_touched`.

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.