cclaw-cli 6.11.0 → 6.13.0

package/dist/integration-fanin.js

@@ -0,0 +1,180 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { exists } from "./fs-utils.js";
+import { readDelegationEvents, recordCclawFanInAudit } from "./delegation.js";
+import { effectiveWorktreeExecutionMode } from "./flow-state.js";
+const execFileAsync = promisify(execFile);
+const WORKTREES_SEG = ".cclaw/worktrees";
+/**
+ * Build a unified diff from `baseRef..HEAD` in the lane worktree and apply it
+ * to the integration branch in the main repo using three-way merge.
+ * On conflict, the integration branch working tree is reset and, when possible,
+ * git HEAD is restored to the branch that was checked out before fan-in.
+ */
+export async function fanInLane(options) {
+    const { projectRoot, laneId, integrationBranch } = options;
+    const workdir = path.join(projectRoot, WORKTREES_SEG, laneId);
+    if (!(await exists(workdir))) {
+        return { ok: false, event: "abandoned", details: `missing lane workdir ${workdir}` };
+    }
+    let integrationRef;
+    try {
+        integrationRef = (await execFileAsync("git", ["rev-parse", "--verify", integrationBranch], {
+            cwd: projectRoot
+        })).stdout.trim();
+    }
+    catch {
+        return {
+            ok: false,
+            event: "abandoned",
+            details: `integration branch/ref not found: ${integrationBranch}`
+        };
+    }
+    let baseRef = options.baseRef?.trim() ?? "";
+    if (baseRef.length === 0) {
+        try {
+            baseRef = (await execFileAsync("git", ["merge-base", integrationRef, "HEAD"], { cwd: workdir })).stdout.trim();
+        }
+        catch (err) {
+            return {
+                ok: false,
+                event: "abandoned",
+                details: `cannot merge-base lane ${laneId} with ${integrationBranch}: ${err instanceof Error ? err.message : String(err)}`
+            };
+        }
+    }
+    const patchFile = path.join(projectRoot, WORKTREES_SEG, `.fanin-${laneId}.patch`);
+    let restoreBranch = null;
+    try {
+        let curBranch = "";
+        try {
+            curBranch = (await execFileAsync("git", ["rev-parse", "--abbrev-ref", "HEAD"], { cwd: projectRoot })).stdout.trim();
+        }
+        catch {
+            curBranch = "";
+        }
+        if (curBranch.length > 0 && curBranch !== integrationBranch && curBranch !== "HEAD") {
+            restoreBranch = curBranch;
+        }
+        const { stdout: diffOut } = await execFileAsync("git", ["diff", `${baseRef}..HEAD`], { cwd: workdir, maxBuffer: 64 * 1024 * 1024 });
+        if (diffOut.trim().length === 0) {
+            return { ok: true, event: "applied", details: "empty diff; nothing to merge" };
+        }
+        await fs.writeFile(patchFile, diffOut, "utf8");
+        await execFileAsync("git", ["checkout", integrationBranch], { cwd: projectRoot });
+        try {
+            await execFileAsync("git", ["apply", "--3way", patchFile], { cwd: projectRoot });
+            return { ok: true, event: "applied", details: `applied lane ${laneId} onto ${integrationBranch}` };
+        }
+        catch (err) {
+            await execFileAsync("git", ["checkout", "--", "."], { cwd: projectRoot }).catch(() => undefined);
+            if (restoreBranch) {
+                await execFileAsync("git", ["checkout", restoreBranch], { cwd: projectRoot }).catch(() => undefined);
+            }
+            const msg = err instanceof Error ? err.message : String(err);
+            return {
+                ok: false,
+                event: "conflict",
+                details: `git apply --3way reported conflicts for lane ${laneId}: ${msg}`
+            };
+        }
+    }
+    finally {
+        await fs.rm(patchFile, { force: true });
+    }
+}
+/**
+ * Returns the canonical CLI hint for resolving fan-in conflicts for a slice.
+ */
+export function buildResolveConflictDispatchHint(sliceId) {
+    return {
+        sliceId,
+        command: `slice-implementer --phase resolve-conflict --slice ${sliceId}`
+    };
+}
+/**
+ * Merge every lane that recorded a completed GREEN `ownerLaneId` for the
+ * active run, then emit `cclaw_fanin_*` audit rows. Does nothing in
+ * `single-tree` mode or when git is unavailable.
+ */
+export async function runTddDeterministicFanInBeforeAdvance(projectRoot, flowState) {
+    if (effectiveWorktreeExecutionMode(flowState) !== "worktree-first") {
+        return { ok: true, issues: [] };
+    }
+    let integrationBranch;
+    try {
+        integrationBranch = (await execFileAsync("git", ["rev-parse", "--abbrev-ref", "HEAD"], { cwd: projectRoot })).stdout.trim();
+    }
+    catch {
+        return {
+            ok: false,
+            issues: ["worktree fan-in: cannot read current git branch (not a repository or detached HEAD unsupported here)."]
+        };
+    }
+    const { events } = await readDelegationEvents(projectRoot);
+    const runId = flowState.activeRunId;
+    const laneToSlices = new Map();
+    for (const e of events) {
+        if (e.runId !== runId || e.stage !== "tdd")
+            continue;
+        if (e.agent !== "slice-implementer")
+            continue;
+        if (e.status !== "completed" || e.phase !== "green")
+            continue;
+        const lane = e.ownerLaneId?.trim();
+        const sid = e.sliceId?.trim();
+        if (!lane || !sid)
+            continue;
+        if (!laneToSlices.has(lane))
+            laneToSlices.set(lane, new Set());
+        laneToSlices.get(lane).add(sid);
+    }
+    if (laneToSlices.size === 0) {
+        return { ok: true, issues: [] };
+    }
+    const issues = [];
+    for (const [laneId, sliceSet] of laneToSlices) {
+        const result = await fanInLane({
+            projectRoot,
+            laneId: laneId,
+            integrationBranch,
+            baseRef: undefined
+        });
+        const sliceIds = [...sliceSet].sort();
+        if (!result.ok && result.event === "conflict") {
+            await recordCclawFanInAudit(projectRoot, {
+                kind: "cclaw_fanin_conflict",
+                runId,
+                laneId,
+                sliceIds,
+                integrationBranch,
+                details: result.details
+            });
+            issues.push(`${result.details} — ${buildResolveConflictDispatchHint(sliceIds[0] ?? "S-1").command}`);
+            continue;
+        }
+        if (!result.ok) {
+            await recordCclawFanInAudit(projectRoot, {
+                kind: "cclaw_fanin_abandoned",
+                runId,
+                laneId,
+                sliceIds,
+                integrationBranch,
+                details: result.details
+            });
+            issues.push(result.details);
+            continue;
+        }
+        await recordCclawFanInAudit(projectRoot, {
+            kind: "cclaw_fanin_applied",
+            runId,
+            laneId,
+            sliceIds,
+            integrationBranch,
+            details: result.details
+        });
+    }
+    return { ok: issues.length === 0, issues };
+}

package/dist/internal/advance-stage/advance.js

@@ -2,7 +2,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { resolveArtifactPath } from "../../artifact-paths.js";
 import { appendDelegation, checkMandatoryDelegations, readDelegationEvents, readDelegationLedger } from "../../delegation.js";
-import { verifyCompletedStagesGateClosure, verifyCurrentStageGateEvidence } from "../../gate-evidence.js";
+import { verifyCompletedStagesGateClosure, verifyCurrentStageGateEvidence, verifyTddWorktreeFanInClosure } from "../../gate-evidence.js";
 import { extractMarkdownSectionBody, learningsParseFailureHumanSummary, parseLearningsSection } from "../../artifact-linter.js";
 import { getAvailableTransitions, getTransitionGuards } from "../../flow-state.js";
 import { appendKnowledge } from "../../knowledge-store.js";
@@ -13,6 +13,7 @@ import { unique } from "./helpers.js";
 import { AUTO_REVIEW_LOOP_GATE_BY_STAGE, reviewLoopArtifactFixHint, reviewLoopEnvelopeExample, validateGateEvidenceShape } from "./review-loop.js";
 import { ensureProactiveDelegationTrace } from "./proactive-delegation-trace.js";
 import { consumeWaiverToken } from "../waiver-grant.js";
+import { runTddDeterministicFanInBeforeAdvance } from "../../integration-fanin.js";
 function resolveSuccessorTransition(stage, track, transitionTargets, satisfiedGuards, selectedTransitionGuards) {
     const natural = transitionTargets[0] ?? null;
     const specialTargets = transitionTargets.filter((target) => target !== natural);
@@ -602,6 +603,20 @@ export async function runAdvanceStage(projectRoot, args, io) {
     }
     const satisfiedGuards = new Set([...nextPassed, ...selectedTransitionGuards]);
     const successor = resolveSuccessorTransition(args.stage, flowState.track, transitionTargets, satisfiedGuards, new Set(selectedTransitionGuards));
+    if (args.stage === "tdd" && successor !== null && successor !== "tdd") {
+        const fanIn = await runTddDeterministicFanInBeforeAdvance(projectRoot, flowState);
+        if (!fanIn.ok) {
+            io.stderr.write(`cclaw internal advance-stage: deterministic worktree fan-in failed:\n${fanIn.issues
+                .map((line) => `  - ${line}`)
+                .join("\n")}\n`);
+            return 1;
+        }
+        const closure = await verifyTddWorktreeFanInClosure(projectRoot, flowState);
+        if (closure.length > 0) {
+            io.stderr.write(`cclaw internal advance-stage: ${closure.join(" | ")}\n`);
+            return 1;
+        }
+    }
     const completedStages = blockedReviewRoute
         ? flowState.completedStages.filter((finished) => finished !== args.stage)
         : flowState.completedStages.includes(args.stage)

package/dist/internal/advance-stage/start-flow.js

@@ -175,7 +175,8 @@ export async function runStartFlow(projectRoot, args, io) {
             guardEvidence,
             stageGateCatalog,
             rewinds: current.rewinds,
-            staleStages: current.staleStages
+            staleStages: current.staleStages,
+            worktreeExecutionMode: current.worktreeExecutionMode ?? "worktree-first"
         };
         const validation = await buildValidationReport(projectRoot, nextState);
         const evidenceIssues = completedStageClosureEvidenceIssues(nextState);
@@ -193,6 +194,7 @@ export async function runStartFlow(projectRoot, args, io) {
         if (nextTaskClass !== undefined) {
             nextState = { ...nextState, taskClass: nextTaskClass };
         }
+        nextState = { ...nextState, worktreeExecutionMode: "worktree-first" };
     }
     if (args.fromIdeaArtifact) {
         const existingHints = nextState.interactionHints ?? {};

package/dist/internal/advance-stage.js

@@ -14,8 +14,9 @@ import { parseAdvanceStageArgs, parseCancelRunArgs, parseHookArgs, parseRewindAr
 import { parseFlowStateRepairArgs, runFlowStateRepair } from "./flow-state-repair.js";
 import { parseWaiverGrantArgs, runWaiverGrant } from "./waiver-grant.js";
 import { FlowStateGuardMismatchError, verifyFlowStateGuard } from "../run-persistence.js";
-import { DelegationTimestampError, DispatchCapError, DispatchDuplicateError, DispatchOverlapError } from "../delegation.js";
+import { DelegationTimestampError, DispatchCapError, DispatchClaimInvalidError, DispatchDuplicateError, DispatchOverlapError } from "../delegation.js";
 import { parsePlanSplitWavesArgs, runPlanSplitWaves } from "./plan-split-waves.js";
+import { runSetWorktreeMode } from "./set-worktree-mode.js";
 /**
  * Subcommands that mutate or consult flow-state.json via the CLI runtime.
  * They all require the sha256 sidecar to match before continuing so a
@@ -28,12 +29,13 @@ const GUARD_ENFORCED_SUBCOMMANDS = new Set([
     "cancel-run",
     "rewind",
     "verify-flow-state-diff",
-    "verify-current-state"
+    "verify-current-state",
+    "set-worktree-mode"
 ]);
 export async function runInternalCommand(projectRoot, argv, io) {
     const [subcommand, ...tokens] = argv;
     if (!subcommand) {
-        io.stderr.write("cclaw internal requires a subcommand: advance-stage | start-flow | cancel-run | rewind | verify-flow-state-diff | verify-current-state | envelope-validate | tdd-red-evidence | tdd-loop-status | early-loop-status | compound-readiness | runtime-integrity | hook | flow-state-repair | waiver-grant | plan-split-waves\n");
+        io.stderr.write("cclaw internal requires a subcommand: advance-stage | start-flow | cancel-run | rewind | verify-flow-state-diff | verify-current-state | envelope-validate | tdd-red-evidence | tdd-loop-status | early-loop-status | compound-readiness | runtime-integrity | hook | flow-state-repair | waiver-grant | plan-split-waves | set-worktree-mode\n");
         return 1;
     }
     try {
@@ -88,7 +90,10 @@ export async function runInternalCommand(projectRoot, argv, io) {
         if (subcommand === "plan-split-waves") {
             return await runPlanSplitWaves(projectRoot, parsePlanSplitWavesArgs(tokens), io);
         }
-        io.stderr.write(`Unknown internal subcommand: ${subcommand}. Expected advance-stage | start-flow | cancel-run | rewind | verify-flow-state-diff | verify-current-state | envelope-validate | tdd-red-evidence | tdd-loop-status | early-loop-status | compound-readiness | runtime-integrity | hook | flow-state-repair | waiver-grant | plan-split-waves\n`);
+        if (subcommand === "set-worktree-mode") {
+            return await runSetWorktreeMode(projectRoot, tokens, io);
+        }
+        io.stderr.write(`Unknown internal subcommand: ${subcommand}. Expected advance-stage | start-flow | cancel-run | rewind | verify-flow-state-diff | verify-current-state | envelope-validate | tdd-red-evidence | tdd-loop-status | early-loop-status | compound-readiness | runtime-integrity | hook | flow-state-repair | waiver-grant | plan-split-waves | set-worktree-mode\n`);
         return 1;
     }
     catch (err) {
@@ -112,6 +117,10 @@ export async function runInternalCommand(projectRoot, argv, io) {
             io.stderr.write(`error: dispatch_cap — ${err.message}\n`);
             return 2;
         }
+        if (err instanceof DispatchClaimInvalidError) {
+            io.stderr.write(`error: dispatch_claim_invalid — ${err.message}\n`);
+            return 2;
+        }
         io.stderr.write(`cclaw internal ${subcommand} failed: ${err instanceof Error ? err.message : String(err)}\n`);
         return 1;
     }

package/dist/internal/plan-split-waves.d.ts

@@ -29,7 +29,7 @@ export interface PlanSplitWavesArgs {
     force: boolean;
     json: boolean;
 }
-export declare const PLAN_SPLIT_DEFAULT_WAVE_SIZE = 25;
+export declare const PLAN_SPLIT_DEFAULT_WAVE_SIZE = 5;
 export declare const PLAN_SPLIT_SMALL_PLAN_THRESHOLD = 50;
 export interface ParsedImplementationUnit {
     id: string;
@@ -42,6 +42,44 @@ export interface ParsedImplementationUnit {
     /** Repo-relative path declarations from the optional `Files:` line. */
     paths: string[];
 }
+export interface ImplementationUnitParallelFields {
+    unitId: string;
+    dependsOn: string[];
+    claimedPaths: string[];
+    parallelizable: boolean;
+    riskTier: "low" | "standard" | "high";
+    lane?: string;
+}
+export interface ParseImplementationUnitParallelOptions {
+    /**
+     * Legacy continuation (v6.13.0): when the plan predates explicit parallel
+     * bullets, units without a `parallelizable:` line default to serial eligibility
+     * in the scheduler (`parallelizable: false`).
+     */
+    legacyParallelDefaultSerial?: boolean;
+}
+/**
+ * Parse v6.13 parallel-metadata bullets from an implementation unit body.
+ * Missing keys use conservative defaults (`dependsOn: []`, `parallelizable: true`
+ * unless `legacyParallelDefaultSerial` is set).
+ */
+export declare function parseImplementationUnitParallelFields(unit: ParsedImplementationUnit, options?: ParseImplementationUnitParallelOptions): ImplementationUnitParallelFields;
+/**
+ * True when the plan has implementation units but any unit is missing v6.13.0
+ * `dependsOn` / `claimedPaths` / `parallelizable` / `riskTier` bullets.
+ */
+export declare function planArtifactLacksV613ParallelMetadata(planMarkdown: string): boolean;
+export declare function compareCanonicalUnitIds(a: string, b: string): number;
+/**
+ * Group implementation units into waves: topological order, then greedy
+ * placement with disjoint `claimedPaths` and `cap` members per wave.
+ */
+export declare function buildConflictAwareWavesFromUnits(units: ParsedImplementationUnit[], cap: number): ParsedImplementationUnit[][];
+export declare function buildParallelExecutionPlanSection(waves: ParsedImplementationUnit[][], cap: number): string;
+/**
+ * Replace or append the managed Parallel Execution Plan block.
+ */
+export declare function upsertParallelExecutionPlanSection(planMarkdown: string, managedBlock: string): string;
 /**
  * Parse `## Implementation Units` section into individual unit blocks.
  * Recognizes the canonical heading shape in the TDD-velocity plan template

package/dist/internal/plan-split-waves.js

@@ -3,11 +3,196 @@ import path from "node:path";
 import { resolveArtifactPath } from "../artifact-paths.js";
 import { exists, writeFileSafe } from "../fs-utils.js";
 import { readFlowState } from "../runs.js";
-export const PLAN_SPLIT_DEFAULT_WAVE_SIZE = 25;
+export const PLAN_SPLIT_DEFAULT_WAVE_SIZE = 5;
 export const PLAN_SPLIT_SMALL_PLAN_THRESHOLD = 50;
 const WAVE_PLANS_DIR = "wave-plans";
 const WAVE_MANAGED_START = "<!-- wave-split-managed-start -->";
 const WAVE_MANAGED_END = "<!-- wave-split-managed-end -->";
+const PARALLEL_EXEC_MANAGED_START = "<!-- parallel-exec-managed-start -->";
+const PARALLEL_EXEC_MANAGED_END = "<!-- parallel-exec-managed-end -->";
+/**
+ * Parse v6.13 parallel-metadata bullets from an implementation unit body.
+ * Missing keys use conservative defaults (`dependsOn: []`, `parallelizable: true`
+ * unless `legacyParallelDefaultSerial` is set).
+ */
+export function parseImplementationUnitParallelFields(unit, options) {
+    const text = unit.body;
+    const pick = (label) => {
+        const re = new RegExp(`^[-*]\\s*\\*{0,2}${label}\\*{0,2}\\s*:\\s*(.*)$`, "imu");
+        for (const rawLine of text.split(/\r?\n/u)) {
+            const line = rawLine.trim();
+            const m = re.exec(line);
+            if (m)
+                return m[1]?.trim();
+        }
+        return undefined;
+    };
+    const id = pick("id") ?? unit.id;
+    const depRaw = pick("dependsOn") ?? pick("depends on") ?? "";
+    const dependsOn = depRaw
+        .split(/,/u)
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0 && !/^none$/iu.test(s));
+    const pathsRaw = pick("claimedPaths") ?? pick("claimed paths") ?? "";
+    const claimedPaths = pathsRaw.length > 0
+        ? pathsRaw
+            .split(",")
+            .map((s) => s.replace(/[`\s]/gu, "").trim())
+            .filter((s) => s.length > 0)
+        : [...unit.paths];
+    const explicitParallel = pick("parallelizable");
+    const parallelRaw = (explicitParallel ?? "true").toLowerCase();
+    let parallelizable = parallelRaw === "true" || parallelRaw === "yes" || parallelRaw === "y";
+    if (options?.legacyParallelDefaultSerial && explicitParallel === undefined) {
+        parallelizable = false;
+    }
+    const riskRaw = (pick("riskTier") ?? pick("risk tier") ?? "standard").toLowerCase();
+    const riskTier = riskRaw === "low" ? "low" : riskRaw === "high" ? "high" : "standard";
+    const laneRaw = pick("lane");
+    const lane = laneRaw && laneRaw.length > 0 ? laneRaw : undefined;
+    return { unitId: id, dependsOn, claimedPaths, parallelizable, riskTier, lane };
+}
+function unitBodyHasV613ParallelBullet(body, label) {
+    const re = new RegExp(`^[-*]\\s*\\*{0,2}${label}\\*{0,2}\\s*:`, "imu");
+    return body.split(/\r?\n/u).some((raw) => re.test(raw.trim()));
+}
+/**
+ * True when the plan has implementation units but any unit is missing v6.13.0
+ * `dependsOn` / `claimedPaths` / `parallelizable` / `riskTier` bullets.
+ */
+export function planArtifactLacksV613ParallelMetadata(planMarkdown) {
+    const units = parseImplementationUnits(planMarkdown);
+    if (units.length === 0)
+        return false;
+    const labels = ["dependsOn", "claimedPaths", "parallelizable", "riskTier"];
+    return units.some((u) => !labels.every((lab) => unitBodyHasV613ParallelBullet(u.body, lab)));
+}
+export function compareCanonicalUnitIds(a, b) {
+    const ma = /^U-(\d+)$/u.exec(a);
+    const mb = /^U-(\d+)$/u.exec(b);
+    if (ma && mb)
+        return Number(ma[1]) - Number(mb[1]);
+    return a.localeCompare(b);
+}
+function topoSortPlanUnits(meta) {
+    const idSet = new Set(meta.map((m) => m.unitId));
+    const incoming = new Map();
+    for (const m of meta)
+        incoming.set(m.unitId, 0);
+    for (const m of meta) {
+        for (const d of m.dependsOn) {
+            if (!idSet.has(d))
+                continue;
+            incoming.set(m.unitId, (incoming.get(m.unitId) ?? 0) + 1);
+        }
+    }
+    const queue = meta
+        .filter((m) => (incoming.get(m.unitId) ?? 0) === 0)
+        .sort((a, b) => compareCanonicalUnitIds(a.unitId, b.unitId));
+    const out = [];
+    while (queue.length > 0) {
+        const m = queue.shift();
+        out.push(m);
+        for (const other of meta) {
+            if (!other.dependsOn.includes(m.unitId))
+                continue;
+            const v = (incoming.get(other.unitId) ?? 0) - 1;
+            incoming.set(other.unitId, v);
+            if (v === 0) {
+                queue.push(other);
+                queue.sort((a, b) => compareCanonicalUnitIds(a.unitId, b.unitId));
+            }
+        }
+    }
+    if (out.length !== meta.length) {
+        return [...meta].sort((a, b) => compareCanonicalUnitIds(a.unitId, b.unitId));
+    }
+    return out;
+}
+/**
+ * Group implementation units into waves: topological order, then greedy
+ * placement with disjoint `claimedPaths` and `cap` members per wave.
+ */
+export function buildConflictAwareWavesFromUnits(units, cap) {
+    const metaList = units.map((u) => parseImplementationUnitParallelFields(u));
+    const ordered = topoSortPlanUnits(metaList);
+    const unitById = new Map(units.map((u) => [parseImplementationUnitParallelFields(u).unitId, u]));
+    const waves = [];
+    const allMetaIds = new Set(metaList.map((m) => m.unitId));
+    for (const m of ordered) {
+        const u = unitById.get(m.unitId);
+        if (!u)
+            continue;
+        let placed = false;
+        for (let wi = 0; wi < waves.length; wi++) {
+            const wave = waves[wi];
+            if (wave.length >= cap)
+                continue;
+            const priorIds = new Set(waves
+                .slice(0, wi)
+                .flat()
+                .map((wu) => parseImplementationUnitParallelFields(wu).unitId));
+            const depsOk = m.dependsOn.every((d) => priorIds.has(d) || !allMetaIds.has(d));
+            if (!depsOk)
+                continue;
+            const pathsInWave = new Set();
+            for (const wu of wave) {
+                for (const p of parseImplementationUnitParallelFields(wu).claimedPaths) {
+                    pathsInWave.add(p);
+                }
+            }
+            const clash = m.claimedPaths.some((p) => pathsInWave.has(p));
+            if (clash)
+                continue;
+            wave.push(u);
+            placed = true;
+            break;
+        }
+        if (!placed) {
+            waves.push([u]);
+        }
+    }
+    return waves;
+}
+export function buildParallelExecutionPlanSection(waves, cap) {
+    const lines = [];
+    lines.push(PARALLEL_EXEC_MANAGED_START);
+    lines.push("## Parallel Execution Plan");
+    lines.push("");
+    lines.push(`- **Cap:** ${cap} parallel units per wave (conflict-aware via \`claimedPaths\`).`);
+    lines.push("");
+    for (let i = 0; i < waves.length; i += 1) {
+        const w = waves[i];
+        const ids = w.map((unit) => parseImplementationUnitParallelFields(unit).unitId);
+        const union = new Set();
+        for (const unit of w) {
+            for (const p of parseImplementationUnitParallelFields(unit).claimedPaths) {
+                union.add(p);
+            }
+        }
+        lines.push(`### Wave ${padWaveIndex(i + 1)}`);
+        lines.push(`- **Members:** ${ids.join(", ")}`);
+        lines.push(`- **Claimed paths union:** ${[...union].sort().join(", ") || "(none)"}`);
+        lines.push("");
+    }
+    lines.push(PARALLEL_EXEC_MANAGED_END);
+    return lines.join("\n");
+}
+/**
+ * Replace or append the managed Parallel Execution Plan block.
+ */
+export function upsertParallelExecutionPlanSection(planMarkdown, managedBlock) {
+    const startIdx = planMarkdown.indexOf(PARALLEL_EXEC_MANAGED_START);
+    const endIdx = planMarkdown.indexOf(PARALLEL_EXEC_MANAGED_END);
+    if (startIdx >= 0 && endIdx > startIdx) {
+        const before = planMarkdown.slice(0, startIdx);
+        const after = planMarkdown.slice(endIdx + PARALLEL_EXEC_MANAGED_END.length);
+        const joined = `${before}${managedBlock}${after}`;
+        return joined.endsWith("\n") ? joined : `${joined}\n`;
+    }
+    const trimmed = planMarkdown.replace(/\s+$/u, "");
+    return `${trimmed}\n\n${managedBlock}\n`;
+}
 /**
  * Parse `## Implementation Units` section into individual unit blocks.
  * Recognizes the canonical heading shape in the TDD-velocity plan template
@@ -193,10 +378,7 @@ export async function runPlanSplitWaves(projectRoot, args, io) {
         }
         return 0;
     }
-    const waves = [];
-    for (let i = 0; i < units.length; i += args.waveSize) {
-        waves.push(units.slice(i, i + args.waveSize));
-    }
+    const waves = buildConflictAwareWavesFromUnits(units, args.waveSize);
     const artifactsDir = path.dirname(planResolved.absPath);
     const wavePlansAbsDir = path.join(artifactsDir, WAVE_PLANS_DIR);
     const waveFileNames = waves.map((_, idx) => `${WAVE_PLANS_DIR}/wave-${padWaveIndex(idx + 1)}.md`);
@@ -217,7 +399,9 @@ export async function runPlanSplitWaves(projectRoot, args, io) {
             await writeFileSafe(path.join(artifactsDir, fileName), body);
         }
         const managed = buildWavePlansSection(waveFileNames);
-        const updatedPlan = upsertWavePlansSection(raw, managed);
+        let updatedPlan = upsertWavePlansSection(raw, managed);
+        const parallelBlock = buildParallelExecutionPlanSection(waves, args.waveSize);
+        updatedPlan = upsertParallelExecutionPlanSection(updatedPlan, parallelBlock);
         if (updatedPlan !== raw) {
             await writeFileSafe(planResolved.absPath, updatedPlan);
         }

package/dist/internal/set-worktree-mode.d.ts

@@ -0,0 +1,10 @@
+import type { Writable } from "node:stream";
+export declare function parseSetWorktreeModeArgs(tokens: string[]): {
+    mode: "single-tree" | "worktree-first";
+} | null;
+/**
+ * Set `flow-state.json::worktreeExecutionMode` without advancing the stage DAG.
+ */
+export declare function runSetWorktreeMode(projectRoot: string, tokens: string[], io: {
+    stderr: Writable;
+}): Promise<number>;

package/dist/internal/set-worktree-mode.js

@@ -0,0 +1,28 @@
+import { readFlowState, writeFlowState } from "../runs.js";
+export function parseSetWorktreeModeArgs(tokens) {
+    let mode = null;
+    for (const token of tokens) {
+        if (token.startsWith("--mode=")) {
+            const raw = token.slice("--mode=".length).trim();
+            if (raw === "single-tree" || raw === "worktree-first") {
+                mode = raw;
+            }
+        }
+    }
+    if (!mode)
+        return null;
+    return { mode };
+}
+/**
+ * Set `flow-state.json::worktreeExecutionMode` without advancing the stage DAG.
+ */
+export async function runSetWorktreeMode(projectRoot, tokens, io) {
+    const parsed = parseSetWorktreeModeArgs(tokens);
+    if (!parsed) {
+        io.stderr.write("cclaw internal set-worktree-mode: usage: --mode=single-tree|worktree-first\n");
+        return 1;
+    }
+    const state = await readFlowState(projectRoot);
+    await writeFlowState(projectRoot, { ...state, worktreeExecutionMode: parsed.mode }, { writerSubsystem: "set-worktree-mode" });
+    return 0;
+}

package/dist/managed-resources.js

@@ -60,6 +60,8 @@ export function isManagedGeneratedPath(relPath) {
         return false;
     if (relPath.startsWith(`${RUNTIME_ROOT}/artifacts/`))
         return false;
+    if (relPath.startsWith(`${RUNTIME_ROOT}/worktrees/`))
+        return false;
     if (relPath.startsWith(`${RUNTIME_ROOT}/archive/`))
         return false;
     if (relPath === `${RUNTIME_ROOT}/state/flow-state.json`)

package/dist/run-persistence.js

@@ -471,6 +471,9 @@ function coerceFlowState(parsed) {
     const taskClass = coerceTaskClass(parsed.taskClass);
     const repoSignals = coerceRepoSignals(parsed.repoSignals);
     const completedStageMeta = sanitizeCompletedStageMeta(parsed.completedStageMeta);
+    const tddCutoverSliceId = coerceTddCutoverSliceId(parsed.tddCutoverSliceId);
+    const worktreeExecutionMode = coerceWorktreeExecutionMode(parsed.worktreeExecutionMode);
+    const legacyContinuation = typeof parsed.legacyContinuation === "boolean" ? parsed.legacyContinuation : undefined;
     const state = {
         schemaVersion: FLOW_STATE_SCHEMA_VERSION,
         activeRunId,
@@ -483,6 +486,9 @@ function coerceFlowState(parsed) {
         ...(taskClass !== undefined ? { taskClass } : {}),
         ...(repoSignals ? { repoSignals } : {}),
         ...(completedStageMeta ? { completedStageMeta } : {}),
+        ...(tddCutoverSliceId ? { tddCutoverSliceId } : {}),
+        ...(worktreeExecutionMode !== undefined ? { worktreeExecutionMode } : {}),
+        ...(legacyContinuation !== undefined ? { legacyContinuation } : {}),
         skippedStages: sanitizeSkippedStages(parsed.skippedStages, track),
         staleStages: sanitizeStaleStages(parsed.staleStages),
         rewinds: sanitizeRewinds(parsed.rewinds),
@@ -492,6 +498,22 @@ function coerceFlowState(parsed) {
     };
     return { state };
 }
+/**
+ * v6.12.0 — best-effort coercion for `tddCutoverSliceId`. Returns the value
+ * only when it matches the canonical slice id shape `S-<digits>`; otherwise
+ * returns null so the field is omitted from the rehydrated state.
+ */
+function coerceTddCutoverSliceId(value) {
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim();
+    return /^S-\d+$/u.test(trimmed) ? trimmed : null;
+}
+function coerceWorktreeExecutionMode(value) {
+    if (value === "single-tree" || value === "worktree-first")
+        return value;
+    return undefined;
+}
 export class CorruptFlowStateError extends Error {
     statePath;
     quarantinedPath;