cclaw-cli 6.13.0 → 6.13.1

package/dist/artifact-linter/tdd.d.ts

@@ -1,4 +1,4 @@
-import type { DelegationEntry } from "../delegation.js";
+import type { DelegationEntry, DelegationEvent } from "../delegation.js";
 import { type LintFinding, type StageLintContext } from "./shared.js";
 /**
  * v6.11.0 — TDD stage linter.
@@ -52,15 +52,28 @@ interface RedCheckpointResult {
     ok: boolean;
     details: string;
 }
+/**
+ * v6.13.1 — detect single-slice dispatch when the merged wave plan
+ * requires parallel ready slice-implementer fan-out.
+ */
+export declare function evaluateWavePlanDispatchIgnored(params: {
+    artifactsDir: string;
+    planMarkdown: string;
+    runEvents: DelegationEvent[];
+    runId: string;
+    slices: Map<string, DelegationEntry[]>;
+    legacyContinuation: boolean;
+}): Promise<LintFinding | null>;
 /**
  * v6.12.0 Phase W — RED checkpoint enforcement. The wave protocol
  * requires ALL Phase A REDs to land before ANY Phase B GREEN starts.
  * The rule is enforced on a per-wave basis, where a wave is defined by
- * `<artifacts-dir>/wave-plans/wave-NN.md` files (when present) listing
- * slice ids. When no wave manifest exists, the linter falls back to a
- * conservative implicit detection: a wave is a contiguous run of
- * `phase=red` events with no other-phase events between them; the rule
- * fires only when the implicit wave has 2+ members.
+ * the managed `## Parallel Execution Plan` block in `05-plan.md` and/or
+ * `<artifacts-dir>/wave-plans/wave-NN.md` files. When no wave manifest
+ * exists, the linter falls back to a conservative implicit detection: a
+ * wave is a contiguous run of `phase=red` events with no other-phase
+ * events between them; the rule fires only when the implicit wave has
+ * 2+ members.
  *
  * @param waveMembers Optional explicit wave manifest. Map key is wave
  * name (e.g. `"W-01"`); value is the set of slice ids in that wave.

package/dist/artifact-linter/tdd.js

@@ -1,6 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import { readDelegationLedger, readDelegationEvents } from "../delegation.js";
+import { loadTddReadySlicePool, readDelegationLedger, readDelegationEvents, selectReadySlices } from "../delegation.js";
+import { mergeParallelWaveDefinitions, parseParallelExecutionPlanWaves, parseWavePlanDirectory } from "../internal/plan-split-waves.js";
 import { evaluateInvestigationTrace, sectionBodyByName } from "./shared.js";
 const SLICE_SUMMARY_START = "<!-- auto-start: tdd-slice-summary -->";
 const SLICE_SUMMARY_END = "<!-- auto-end: tdd-slice-summary -->";
@@ -26,8 +27,17 @@ const SLICES_INDEX_END = "<!-- auto-end: slices-index -->";
  *    via `## Slices Index`.
  */
 export async function lintTddStage(ctx) {
-    const { projectRoot, discoveryMode, raw, absFile, sections, findings, parsedFrontmatter, worktreeExecutionMode } = ctx;
+    const { projectRoot, discoveryMode, raw, absFile, sections, findings, parsedFrontmatter, worktreeExecutionMode, legacyContinuation } = ctx;
     void parsedFrontmatter;
+    const artifactsDir = path.dirname(absFile);
+    const planPath = path.join(artifactsDir, "05-plan.md");
+    let planRaw = "";
+    try {
+        planRaw = await fs.readFile(planPath, "utf8");
+    }
+    catch {
+        planRaw = "";
+    }
     evaluateInvestigationTrace(ctx, "Watched-RED Proof");
     const delegationLedger = await readDelegationLedger(ctx.projectRoot);
     const activeRunEntries = delegationLedger.entries.filter((entry) => entry.stage === "tdd" && entry.runId === delegationLedger.runId);
@@ -176,7 +186,7 @@ export async function lintTddStage(ctx) {
     // (size >= 2). Sequential per-slice runs (red→green→refactor in a
     // tight loop) form size-1 implicit waves and are unaffected.
     if (eventsActive) {
-        const waveManifest = await readWaveManifest(path.dirname(absFile));
+        const waveManifest = await readMergedWaveManifestForCheckpoint(artifactsDir, planRaw);
         const checkpointResult = evaluateRedCheckpoint(slicesByEvents, waveManifest);
         if (!checkpointResult.ok) {
             findings.push({
@@ -203,52 +213,69 @@ export async function lintTddStage(ctx) {
     }
     const { events: jsonlEvents, fanInAudits } = await readDelegationEvents(projectRoot);
     const runEvents = jsonlEvents.filter((e) => e.runId === delegationLedger.runId);
+    if (eventsActive && planRaw.length > 0) {
+        const ignoredWave = await evaluateWavePlanDispatchIgnored({
+            artifactsDir,
+            planMarkdown: planRaw,
+            runEvents,
+            runId: delegationLedger.runId,
+            slices: slicesByEvents,
+            legacyContinuation
+        });
+        if (ignoredWave) {
+            findings.push(ignoredWave);
+        }
+    }
     if (eventsActive && worktreeExecutionMode === "worktree-first") {
         const terminalPhases = new Set([
-            "green",
             "refactor",
             "refactor-deferred",
             "resolve-conflict"
         ]);
-        const missingClaim = new Set();
+        const missingGreenMeta = new Set();
         for (const ev of runEvents) {
             if (ev.stage !== "tdd" || ev.agent !== "slice-implementer")
                 continue;
-            if (ev.status !== "completed" && ev.status !== "failed")
+            if (ev.status !== "completed" || ev.phase !== "green")
                 continue;
-            if (!ev.phase || !terminalPhases.has(ev.phase))
+            if (typeof ev.sliceId !== "string")
                 continue;
             const tok = ev.claimToken?.trim() ?? "";
-            if (tok.length === 0 && typeof ev.sliceId === "string") {
-                missingClaim.add(ev.sliceId);
+            const lane = ev.ownerLaneId?.trim() ?? "";
+            const lease = ev.leasedUntil?.trim() ?? "";
+            if (tok.length === 0 || lane.length === 0 || lease.length === 0) {
+                missingGreenMeta.add(ev.sliceId);
             }
         }
-        if (missingClaim.size > 0) {
+        if (missingGreenMeta.size > 0) {
             findings.push({
-                section: "tdd_slice_claim_token_missing",
+                section: "tdd_slice_lane_metadata_missing",
                 required: true,
-                rule: "Worktree-first: terminal slice-implementer rows must echo --claim-token. Remediation: pass the same --claim-token used on the scheduled row for every completed/failed terminal phase.",
+                rule: "Worktree-first: every completed slice-implementer phase=green row must record claimToken, ownerLaneId (--lane-id), and leasedUntil (--lease-until).",
                 found: false,
-                details: `Slices missing claim token on terminal rows: ${[...missingClaim].join(", ")}.`
+                details: `Slices missing one or more lane fields on GREEN: ${[...missingGreenMeta].sort().join(", ")}. Remediation: include --claim-token, --lane-id, and --lease-until on every slice-implementer --phase green delegation-record write (schedule through completion); the hook fails fast with dispatch_lane_metadata_missing when they are omitted.`
             });
         }
-        const missingLane = new Set();
+        const missingClaim = new Set();
         for (const ev of runEvents) {
             if (ev.stage !== "tdd" || ev.agent !== "slice-implementer")
                 continue;
-            if (ev.status !== "completed" || ev.phase !== "green")
+            if (ev.status !== "completed" && ev.status !== "failed")
                 continue;
-            if (!ev.ownerLaneId?.trim() && typeof ev.sliceId === "string") {
-                missingLane.add(ev.sliceId);
+            if (!ev.phase || !terminalPhases.has(ev.phase))
+                continue;
+            const tok = ev.claimToken?.trim() ?? "";
+            if (tok.length === 0 && typeof ev.sliceId === "string") {
+                missingClaim.add(ev.sliceId);
             }
         }
-        if (missingLane.size > 0) {
+        if (missingClaim.size > 0) {
             findings.push({
-                section: "tdd_slice_worktree_metadata_missing",
+                section: "tdd_slice_claim_token_missing",
                 required: true,
-                rule: "Worktree-first: completed GREEN rows must record --lane-id (ownerLaneId) for the lane worktree.",
+                rule: "Worktree-first: terminal slice-implementer rows (refactor / refactor-deferred / resolve-conflict) must echo --claim-token. Remediation: pass the same --claim-token used on the scheduled row for every completed/failed terminal phase.",
                 found: false,
-                details: `Slices missing ownerLaneId on GREEN completion: ${[...missingLane].join(", ")}.`
+                details: `Slices missing claim token on non-GREEN terminal rows: ${[...missingClaim].join(", ")}.`
             });
         }
         const conflictSlices = [
@@ -338,7 +365,6 @@ export async function lintTddStage(ctx) {
     const completedSliceImplementers = activeRunEntries.filter((entry) => entry.agent === "slice-implementer" && entry.status === "completed");
     const fanOutDetected = completedSliceImplementers.length > 1;
     if (fanOutDetected) {
-        const artifactsDir = path.dirname(absFile);
         const cohesionContractMarkdownPath = path.join(artifactsDir, "cohesion-contract.md");
         const cohesionContractJsonPath = path.join(artifactsDir, "cohesion-contract.json");
         let cohesionContractFound = true;
@@ -418,7 +444,6 @@ export async function lintTddStage(ctx) {
     // Phase S — sharded slice files. Validate per-slice file presence
     // and required headings. `tdd-slices/` is optional; missing folder
     // simply means main-only mode (legacy fallback).
-    const artifactsDir = path.dirname(absFile);
     const slicesDir = path.join(artifactsDir, "tdd-slices");
     const sliceFiles = await listSliceFiles(slicesDir);
     for (const sliceFile of sliceFiles) {
@@ -694,15 +719,110 @@ export function evaluateSliceImplementerCoverage(slices) {
     }
     return { missing };
 }
+async function readMergedWaveManifestForCheckpoint(artifactsDir, planMarkdown) {
+    try {
+        const merged = mergeParallelWaveDefinitions(parseParallelExecutionPlanWaves(planMarkdown), await parseWavePlanDirectory(artifactsDir));
+        if (merged.length === 0)
+            return null;
+        const map = new Map();
+        for (const w of merged) {
+            map.set(w.waveId, new Set(w.members.map((m) => m.sliceId)));
+        }
+        return map.size > 0 ? map : null;
+    }
+    catch {
+        return null;
+    }
+}
+function sliceRefactorTerminal(sliceId, slices) {
+    const rows = slices.get(sliceId);
+    if (!rows)
+        return false;
+    return rows.some((e) => e.agent === "slice-implementer" &&
+        (e.phase === "refactor" || e.phase === "refactor-deferred") &&
+        (e.status === "completed" || e.status === "failed"));
+}
+/**
+ * v6.13.1 — detect single-slice dispatch when the merged wave plan
+ * requires parallel ready slice-implementer fan-out.
+ */
+export async function evaluateWavePlanDispatchIgnored(params) {
+    let merged;
+    try {
+        merged = mergeParallelWaveDefinitions(parseParallelExecutionPlanWaves(params.planMarkdown), await parseWavePlanDirectory(params.artifactsDir));
+    }
+    catch {
+        return null;
+    }
+    if (merged.length === 0)
+        return null;
+    let pool;
+    try {
+        pool = await loadTddReadySlicePool(params.planMarkdown, params.artifactsDir, {
+            legacyParallelDefaultSerial: params.legacyContinuation
+        });
+    }
+    catch {
+        return null;
+    }
+    if (pool.length === 0)
+        return null;
+    const completedUnitIds = new Set();
+    for (const u of pool) {
+        if (sliceRefactorTerminal(u.sliceId, params.slices)) {
+            completedUnitIds.add(u.unitId);
+        }
+    }
+    const scoped = params.runEvents.filter((e) => e.runId === params.runId);
+    const tail = scoped.slice(-20);
+    const implInTail = new Set();
+    for (const e of tail) {
+        if (e.agent === "slice-implementer" && typeof e.sliceId === "string" && e.sliceId.length > 0) {
+            implInTail.add(e.sliceId);
+        }
+    }
+    if (implInTail.size !== 1)
+        return null;
+    for (const wave of merged) {
+        const waveSliceSet = new Set(wave.members.map((m) => m.sliceId));
+        const wavePool = pool.filter((u) => waveSliceSet.has(u.sliceId));
+        if (wavePool.length < 2)
+            continue;
+        const waveIncomplete = wave.members.some((m) => !sliceRefactorTerminal(m.sliceId, params.slices));
+        if (!waveIncomplete)
+            continue;
+        const ready = selectReadySlices(wavePool, {
+            cap: Math.max(32, wavePool.length),
+            completedUnitIds,
+            activePathHolders: [],
+            legacyContinuation: params.legacyContinuation
+        });
+        if (ready.length < 2)
+            continue;
+        const only = [...implInTail][0];
+        const missed = ready.map((r) => r.sliceId).filter((s) => s !== only);
+        if (missed.length === 0)
+            continue;
+        return {
+            section: "tdd_wave_plan_ignored",
+            required: true,
+            rule: "When the Parallel Execution Plan (or wave-plans/) defines an open wave with two or more ready parallelizable slices, the controller must fan out slice-implementer work for each ready slice instead of serializing to one slice only.",
+            found: false,
+            details: `Wave ${wave.waveId}: scheduler-ready members ${ready.map((r) => r.sliceId).join(", ")}; last 20 delegation events show slice-implementer only for ${only}. Missed parallel dispatch: ${missed.join(", ")}. Remediation: load \`05-plan.md\` (Parallel Execution Plan) and \`wave-plans/\` before routing, launch the wave (AskQuestion only when waveCount>=2 and single-slice is a real alternative), then dispatch GREEN+DOC for every ready slice with mandatory worktree-first flags on GREEN.`
+        };
+    }
+    return null;
+}
 /**
  * v6.12.0 Phase W — RED checkpoint enforcement. The wave protocol
  * requires ALL Phase A REDs to land before ANY Phase B GREEN starts.
  * The rule is enforced on a per-wave basis, where a wave is defined by
- * `<artifacts-dir>/wave-plans/wave-NN.md` files (when present) listing
- * slice ids. When no wave manifest exists, the linter falls back to a
- * conservative implicit detection: a wave is a contiguous run of
- * `phase=red` events with no other-phase events between them; the rule
- * fires only when the implicit wave has 2+ members.
+ * the managed `## Parallel Execution Plan` block in `05-plan.md` and/or
+ * `<artifacts-dir>/wave-plans/wave-NN.md` files. When no wave manifest
+ * exists, the linter falls back to a conservative implicit detection: a
+ * wave is a contiguous run of `phase=red` events with no other-phase
+ * events between them; the rule fires only when the implicit wave has
+ * 2+ members.
  *
  * @param waveMembers Optional explicit wave manifest. Map key is wave
  * name (e.g. `"W-01"`); value is the set of slice ids in that wave.
@@ -783,42 +903,6 @@ export function evaluateRedCheckpoint(slices, waveMembers = null) {
             "Dispatch ALL Phase A test-author --phase red calls in one message, verify every phase=red event lands with non-empty evidenceRefs, and only then dispatch Phase B slice-implementer --phase green + slice-documenter --phase doc fan-out."
     };
 }
-/**
- * Read explicit wave manifest from `<artifacts-dir>/wave-plans/wave-NN.md`
- * files. Returns a map from wave name to the set of slice ids it
- * contains. Slice ids are extracted via `S-<digits>` regex matches in
- * each wave file. Returns null when no wave files exist or all are
- * empty/unparseable.
- */
-async function readWaveManifest(artifactsDir) {
-    const wavePlansDir = path.join(artifactsDir, "wave-plans");
-    let entries = [];
-    try {
-        entries = await fs.readdir(wavePlansDir);
-    }
-    catch {
-        return null;
-    }
-    const waves = new Map();
-    for (const name of entries) {
-        const match = /^wave-(\d+)\.md$/u.exec(name);
-        if (!match)
-            continue;
-        const wavePath = path.join(wavePlansDir, name);
-        let body = "";
-        try {
-            body = await fs.readFile(wavePath, "utf8");
-        }
-        catch {
-            continue;
-        }
-        const ids = extractSliceIdsFromBody(body);
-        if (ids.length === 0)
-            continue;
-        waves.set(`W-${match[1]}`, new Set(ids));
-    }
-    return waves.size > 0 ? waves : null;
-}
 const LEGACY_PER_SLICE_SECTIONS = [
     "Test Discovery",
     "RED Evidence",

package/dist/content/hooks.js

@@ -294,6 +294,19 @@ async function readRunId(root) {
   }
 }
 
+async function readWorktreeExecutionModeInline(root) {
+  try {
+    const raw = await fs.readFile(path.join(root, RUNTIME_ROOT, "state", "flow-state.json"), "utf8");
+    const parsed = JSON.parse(raw);
+    if (parsed && parsed.worktreeExecutionMode === "worktree-first") {
+      return "worktree-first";
+    }
+    return "single-tree";
+  } catch {
+    return "single-tree";
+  }
+}
+
 async function readDelegationEvents(root) {
   try {
     const raw = await fs.readFile(path.join(root, RUNTIME_ROOT, "state", "delegation-events.jsonl"), "utf8");
@@ -1265,6 +1278,33 @@ async function main() {
     }
   }
 
+  if (
+    clean.stage === "tdd" &&
+    clean.agent === "slice-implementer" &&
+    clean.phase === "green" &&
+    (await readWorktreeExecutionModeInline(root)) === "worktree-first"
+  ) {
+    const tok = typeof clean.claimToken === "string" ? clean.claimToken.trim() : "";
+    const lane = typeof clean.ownerLaneId === "string" ? clean.ownerLaneId.trim() : "";
+    const lease = typeof clean.leasedUntil === "string" ? clean.leasedUntil.trim() : "";
+    if (tok.length === 0 || lane.length === 0 || lease.length === 0) {
+      const missing = [];
+      if (tok.length === 0) missing.push("--claim-token");
+      if (lane.length === 0) missing.push("--lane-id");
+      if (lease.length === 0) missing.push("--lease-until");
+      emitErrorJson(
+        "dispatch_lane_metadata_missing",
+        {
+          missing,
+          remediation:
+            "worktree-first mode requires --claim-token, --lane-id, and --lease-until on every slice-implementer --phase green delegation-record write (from scheduled through completed)."
+        },
+        json
+      );
+      return;
+    }
+  }
+
   await persistEntry(root, runId, clean, event);
   process.stdout.write(JSON.stringify({ ok: true, event }, null, 2) + "\\n");
 }

package/dist/content/skills.js

@@ -4,6 +4,7 @@ import { FLOW_STAGES } from "../types.js";
 import { behaviorAnchorFor, stageExamples } from "./examples.js";
 import { INVESTIGATION_DISCIPLINE_BLOCK } from "./templates.js";
 import { reviewStackAwareRoutes, reviewStackAwareRoutingSummary, stageAutoSubagentDispatch, stageSchema, stageTrackRenderContext } from "./stage-schema.js";
+import { renderTrackTerminology } from "./track-render-context.js";
 import { referencePatternsForStage } from "./reference-patterns.js";
 import { harnessDelegationRecipes } from "../harness-adapters.js";
 const VERIFICATION_STAGES = ["tdd", "review", "ship"];
@@ -196,16 +197,20 @@ ONE slice = THREE dispatches, in this order. Do not skip, do not collapse.
    The file-overlap scheduler auto-allows parallel dispatch because \`claimedPaths\` are disjoint. Fire BOTH calls in the same message — never serialize independent work.
 4. **REFACTOR** — \`Task("slice-implementer --slice S-<id> --phase refactor")\` OR \`--phase refactor-deferred --refactor-rationale '<why>'\`.
 
+**Rule 1 (v6.13.1):** Before any slice-routing question, read \`<artifacts-dir>/05-plan.md\` (managed \`## Parallel Execution Plan\`) **and** list \`<artifacts-dir>/wave-plans/wave-NN.md\`. Merge mentally: Parallel Execution Plan first, wave files second; duplicate slices with conflicting wave membership are invalid. If the merged plan shows a wave with **two or more** scheduler-ready slices, issue **exactly one** \`AskQuestion\`: \`Launch wave W-NN with N parallel lanes (S-a, S-b, ...)?\` with default option **launch wave** and alternate **single-slice instead**. Do not ask "which slice next?" when that question is redundant (single ready slice or no wave). After **launch wave** confirmation, execute RED checkpoint → parallel GREEN+DOC → per-lane REFACTOR without further routing asks. After **single-slice instead**, fall back to the legacy single-slice ritual. **Wave dispatch resume:** if part of the wave is already done, parallelize only the remaining members.
+
 **FORBIDDEN:**
 - Controller writing GREEN production code. ALL GREEN goes through \`slice-implementer\` — linter rule \`tdd_slice_implementer_missing\` blocks the gate.
 - Controller writing per-slice prose into legacy \`06-tdd.md\` sections (Test Discovery / RED Evidence / GREEN Evidence / Watched-RED Proof / Vertical Slice Cycle / Per-Slice Review / Failure Analysis / Acceptance Mapping). \`slice-documenter\` owns \`tdd-slices/S-<id>.md\` — \`tdd_slice_documenter_missing\` blocks the gate.
 - Hand-editing auto-render blocks between \`auto-start: tdd-slice-summary\` / \`auto-start: slices-index\` markers — overwritten every lint.
 
-Delegation-record signature: \`node .cclaw/hooks/delegation-record.mjs --stage=tdd --agent=<agent> --mode=mandatory --status=<...> --span-id=<id> --dispatch-id=<id> --dispatch-surface=<surface> --agent-definition-path=<path> --slice=S-<id> --phase=<red|green|refactor|refactor-deferred|doc> [--paths=<csv>] [--refactor-rationale=<why>] [--ack-ts=<iso>] [--evidence-ref=<ref>] --json\`.
+Delegation-record signature (extend with lane metadata for every GREEN row in \`worktree-first\`):
+
+\`node .cclaw/hooks/delegation-record.mjs --stage=tdd --agent=slice-implementer --mode=mandatory --status=scheduled --span-id=<id> --dispatch-id=<id> --dispatch-surface=<surface> --agent-definition-path=<path> --slice=S-1 --phase=green --paths=src/a.ts --claim-token=<opaque> --lane-id=<lane> --lease-until=<iso8601> --json\`
 
-## Wave Batch Mode (v6.12.0+)
+## Wave Batch Mode (v6.13.1+)
 
-Trigger: any \`<artifacts-dir>/wave-plans/wave-NN.md\` exists, OR 2+ slices have disjoint \`claimedPaths\`. Cap = 5 \`slice-implementer\` lanes (10 subagents incl. paired documenters) via \`MAX_PARALLEL_SLICE_IMPLEMENTERS\`.
+**Triggers:** managed \`## Parallel Execution Plan\` in \`05-plan.md\` **or** any \`<artifacts-dir>/wave-plans/wave-NN.md\`, OR 2+ slices with disjoint \`claimedPaths\`. Cap = 5 \`slice-implementer\` lanes (10 subagents incl. paired documenters) via \`MAX_PARALLEL_SLICE_IMPLEMENTERS\`. **Preconditions:** Load both sources before routing. Worktree-first: every GREEN delegation-record MUST include \`--claim-token\`, \`--lane-id\`, \`--lease-until\` (hook exits \`2\`, \`dispatch_lane_metadata_missing\` otherwise).
 
 **Phase A — RED checkpoint** — ONE message, all test-authors:
 \`\`\`
@@ -215,20 +220,18 @@ Task("test-author --slice S-3 --phase red")
 \`\`\`
 Wait for ALL Phase A REDs to land with non-empty \`evidenceRefs\` before Phase B. Linter \`tdd_red_checkpoint_violation\` (required: true) blocks any wave where a \`phase=green\` \`completedTs\` precedes the wave's last \`phase=red\` \`completedTs\`.
 
-**Phase B — GREEN+DOC fan-out** — ONE message, paired implementer+documenter Tasks per slice:
+**Phase B — GREEN+DOC fan-out** — ONE message; pair per slice (repeat for each lane, flags unique per lane):
+
 \`\`\`
-Task("slice-implementer --slice S-1 --phase green --paths <S-1 prod>")
+Task("slice-implementer --slice S-1 --phase green --paths <prod> --claim-token=<t> --lane-id=<lane-1> --lease-until=<iso>")
 Task("slice-documenter  --slice S-1 --phase doc   --paths <artifacts-dir>/tdd-slices/S-1.md")
-Task("slice-implementer --slice S-2 --phase green --paths <S-2 prod>")
-Task("slice-documenter  --slice S-2 --phase doc   --paths <artifacts-dir>/tdd-slices/S-2.md")
 \`\`\`
-Launch ALL Phase B pairs in ONE message. **Never serialize independent work.**
 
-**Phase C — REFACTOR per slice** — after GREEN+DOC evidence is recorded, dispatch \`slice-implementer --phase refactor\` or \`--phase refactor-deferred\` per slice (may be parallelized when lanes stay disjoint).
+Launch every slice's pair in that same message. **Never serialize independent work.**
 
-**Fan-in (v6.13.0+, worktree-first default)** — each \`slice-implementer\` GREEN row should record \`--claim-token\`, \`--lane-id\`, and \`--lease-until\` per the delegation hook. On successful TDD stage-complete, the runtime performs deterministic \`git apply --3way\` fan-in from each lane worktree onto the current integration branch (no \`-X ours/theirs\`). Conflicts emit \`cclaw_fanin_conflict\` audit rows; resolve with \`slice-implementer --phase resolve-conflict\` then re-run stage-complete. When 2+ parallel lanes finish a wave, still dispatch \`integration-overseer\` so cohesion-contract evidence exists before review.
+**Phase C — REFACTOR per slice** — after GREEN+DOC lands, dispatch refactor/refactor-deferred per slice. **Fan-in (worktree-first):** echo claim/lane/lease on completed GREEN rows; stage-complete runs deterministic \`git apply --3way\` (no \`-X ours/theirs\`). Conflicts: \`slice-implementer --phase resolve-conflict\`. With 2+ lanes, still dispatch \`integration-overseer\` before review.
 
-**slice-documenter** may mark prose \`provisional\` until GREEN is proven; finalize \`tdd-slices/S-<id>.md\` after GREEN evidence is recorded.
+**slice-documenter:** record the \`phase=doc\` row in the same message as GREEN; write a **provisional** row in \`tdd-slices/S-<id>.md\` immediately at dispatch, then **finalize** that file after the matching \`slice-implementer\` \`phase=green\` event lands (evidence-backed prose, not guesswork before GREEN exists).
 
 `;
 }
@@ -655,7 +658,7 @@ If you are about to violate the Iron Law, STOP. No amount of urgency, partial pr
 
 </EXTREMELY-IMPORTANT>
 
-${tddTopOfSkillBlock(stage)}${quickStartBlock(stage, track)}
+${renderTrackTerminology(tddTopOfSkillBlock(stage), trackContext)}${quickStartBlock(stage, track)}
 
 ${STAGE_LANGUAGE_POLICY_POINTER}
 ## Philosophy

package/dist/content/stages/tdd.js

@@ -37,29 +37,29 @@ export const TDD = {
     },
     executionModel: {
         checklist: [
-            "Select vertical slice — pick one source item from the active track (plan task on standard/medium, spec AC or bug reproduction slice on quick). Do not batch multiple tasks. Before starting, read `.cclaw/state/ralph-loop.json` (`loopIteration`, `acClosed[]`, `redOpenSlices[]`) so you skip cycles already closed. If `redOpenSlices[]` is non-empty, repair or explicitly park those slices before opening a new RED.",
+            "**Wave dispatch (v6.13.1):** Before routing, read the Parallel Execution Plan (managed block in the track planning artifact) and `<artifacts-dir>/wave-plans/`. Multi-ready waves: one AskQuestion (launch wave vs single-slice); then RED checkpoint, parallel GREEN+DOC with worktree-first flags, per-lane REFACTOR. Resume partial waves by parallelizing remaining members only (see top-of-skill `## Wave Batch Mode`).",
+            "Select vertical slice — the active wave plan (or single ready slice) defines work. Do not ask \"which slice next?\" when the plan already resolves it. Before starting, read `.cclaw/state/ralph-loop.json` (`loopIteration`, `acClosed[]`, `redOpenSlices[]`) so you skip cycles already closed. If `redOpenSlices[]` is non-empty, repair or explicitly park those slices before opening a new RED.",
             "Map to acceptance criterion — identify the specific spec criterion this test proves.",
             "Discover the test surface — inspect existing tests, fixtures, helpers, test commands, and nearby assertions before authoring RED. Reuse the local test style unless the slice genuinely needs a new pattern.",
             "Run a system-wide impact check — name callbacks, state transitions, interfaces, schemas, CLI/config/API contracts, persistence, or event boundaries that this slice can affect. Add RED coverage for each affected public contract or record why it is out of scope.",
             "Source/test preflight — before production edits, classify planned paths using test-path patterns; verify the RED touches a test path and the GREEN touches only source paths needed for the failing behavior.",
             "Use the mandatory `test-author` delegation for RED — after discovery and impact check, dispatch with `--slice S-<id> --phase red`. Produce failing behavior tests only (no production edits) and let the harness record the dispatch via the generated `delegation-record` hook. Set `CCLAW_ACTIVE_AGENT=tdd-red` when the harness supports phase labels.",
             "RED: do NOT hand-edit `## Watched-RED Proof`, `## Vertical Slice Cycle`, or `## RED Evidence` markdown tables. The linter auto-renders them from `delegation-events.jsonl` slice phase rows; manual edits inside the auto-render markers are overwritten on the next lint.",
-            "Dispatch the `slice-implementer` for GREEN with `--slice S-<id> --phase green` and explicit `--paths` so the file-overlap scheduler can auto-allow parallel slices. Attach an evidence ref (test path, span ref, or pasted-output pointer) so the Vertical Slice Cycle row is well-formed. Set `CCLAW_ACTIVE_AGENT=tdd-green` when the harness supports phase labels.",
+            "Dispatch the `slice-implementer` for GREEN with `--slice S-<id> --phase green` and explicit `--paths` so the file-overlap scheduler can auto-allow parallel slices. When `flow-state.json::worktreeExecutionMode` is `worktree-first`, **mandatory** flags on every GREEN delegation-record row: `--claim-token=<opaque> --lane-id=<lane> --lease-until=<iso8601>`. Attach an evidence ref so the Vertical Slice Cycle row is well-formed. Set `CCLAW_ACTIVE_AGENT=tdd-green` when the harness supports phase labels.",
             "GREEN: Run full suite — execute ALL tests, not just the ones you wrote. The full suite must be GREEN.",
             "GREEN: Verify no regressions — if any existing test breaks, fix the regression before proceeding.",
             "Run verification-before-completion discipline for the slice — capture a fresh test command, explicit PASS/FAIL status, and a config-aware ref (commit SHA when VCS is present/required, or no-vcs attestation when allowed).",
             "REFACTOR: re-dispatch the `slice-implementer` (or `test-author`) with `--phase refactor` once GREEN holds, OR `--phase refactor-deferred --refactor-rationale \"<why>\"` to close the slice without a refactor pass. Both options are recorded as a delegation event; the linter accepts either as REFACTOR coverage. Set `CCLAW_ACTIVE_AGENT=tdd-refactor` when the harness supports phase labels.",
-            "DOC (parallel, mandatory v6.12.0): dispatch `slice-documenter --slice S-<id> --phase doc --paths <artifacts-dir>/tdd-slices/S-<id>.md` IN PARALLEL with `slice-implementer --phase green` for the same slice — ONE message with TWO concurrent Task calls. The documenter only writes `tdd-slices/S-<id>.md`, so its `--paths` are disjoint from the implementer's production paths and the file-overlap scheduler auto-allows the parallel dispatch. Linter rule `tdd_slice_documenter_missing` blocks the gate when the `phase=doc` event is absent (regardless of `discoveryMode`). v6.13.0: documenter output may remain `provisional` until GREEN evidence exists; finalize the slice file after GREEN is recorded.",
-            "## Wave Batch Mode (v6.13+) — (A) RED checkpoint across all wave members before any GREEN in that wave. (B) Parallel implementer+documenter fan-out across multiple slices when paths are disjoint and claims/leases are valid (`--claim-token`, `--lane-id`, `--lease-until`). (C) Per-lane REFACTOR or refactor-deferred. (D) Deterministic git fan-in at TDD stage-complete merges lane diffs with `git apply --3way`; unresolved conflicts block advance until `--phase resolve-conflict` succeeds.",
+            "DOC (parallel, mandatory v6.12.0): dispatch `slice-documenter --slice S-<id> --phase doc --paths <artifacts-dir>/tdd-slices/S-<id>.md` IN PARALLEL with `slice-implementer --phase green` for the same slice — ONE message with TWO concurrent Task calls. The documenter only writes `tdd-slices/S-<id>.md`, so its `--paths` are disjoint from the implementer's production paths and the file-overlap scheduler auto-allows the parallel dispatch. **Provisional-then-finalize:** append a provisional row/section in `tdd-slices/S-<id>.md` at dispatch time, then finalize that artifact after the matching `phase=green` event records evidence (never treat guesses as final before GREEN lands). Linter rule `tdd_slice_documenter_missing` blocks the gate when the `phase=doc` event is absent (regardless of `discoveryMode`).",
             "**slice-documenter writes per-slice prose** (test discovery, system-wide impact check, RED/GREEN/REFACTOR notes, acceptance mapping, failure analysis) into `tdd-slices/S-<id>.md`. Controller does NOT touch this content. When logging a `green` row, attach the closed acceptance-criterion IDs in `acIds` so Ralph Loop status counts them.",
             "Annotate traceability — link to the active track's source: plan task ID + spec criterion on standard/medium, or spec acceptance item / bug reproduction slice on quick.",
             "**Boundary with review (do NOT escalate single-slice findings to whole-diff review).** `tdd.Per-Slice Review` OWNS severity-classified findings WITHIN one slice (correctness, edge cases, regression). `review` OWNS whole-diff Layer 1 (spec compliance) plus Layer 2 (cross-slice integration, security sweep, dependency/version audit, observability). When a single-slice finding genuinely needs whole-diff escalation, surface it in `06-tdd.md > Per-Slice Review` first; review will cite it (not re-classify) and the cross-artifact-duplication linter requires matching severity/disposition.",
             "Per-Slice Review (conditional) — if the slice meets any trigger (touchCount >= filesChangedThreshold, touchPaths match touchTriggers, or highRisk=true), append a `## Per-Slice Review` entry for this slice before moving on (see the dedicated section below).",
-            "Repeat for each slice — return to step 1 for the next plan slice."
+            "Repeat for each slice — when not in multi-slice wave mode, return to wave-plan discovery; otherwise continue the active wave until members close.",
         ],
         interactionProtocol: [
-            "Pick one vertical slice at a time: source item, RED test, GREEN implementation, REFACTOR, and verification evidence move together.",
-            "Slice implementers are sequential by default. Parallel implementers are allowed only when (a) lanes touch non-overlapping files (the file-overlap scheduler auto-allows parallel when `--paths` are disjoint), and (b) an `integration-overseer` is dispatched after the parallel lanes and writes cohesion-evidence into the artifact before the gate is marked passed.",
+            "Pick one vertical slice at a time **only when** the merged wave plan leaves a single scheduler-ready slice or the operator chose single-slice mode. Parallel implementers are allowed when (a) lanes touch non-overlapping files (the file-overlap scheduler auto-allows parallel when `--paths` are disjoint), and (b) an `integration-overseer` is dispatched after the parallel lanes and writes cohesion-evidence into the artifact before the gate is marked passed.",
+            "Slice implementers are sequential only when the plan serializes work; prefer wave-parallel GREEN+DOC when the Parallel Execution Plan marks multiple ready members.",
             "Controller owns orchestration. For each slice S-<id>, dispatch in this order: (1) `test-author --slice S-<id> --phase red` (RED-only, no production edits), (2) `slice-implementer --slice S-<id> --phase green --paths <comma-separated>` for GREEN, (3) re-dispatch `--phase refactor` or `--phase refactor-deferred --refactor-rationale \"<why>\"` to close REFACTOR. Each dispatch records a row in `delegation-events.jsonl` and the linter auto-derives the Watched-RED + Vertical Slice Cycle tables from those rows. Do NOT hand-edit those tables.",
             "Before writing RED tests, discover relevant existing tests and commands so the new test extends the suite instead of fighting it.",
             "Before implementation, perform a system-wide impact check across callbacks, state, interfaces, schemas, and external contracts touched by the slice.",

package/dist/content/start-command.js

@@ -115,6 +115,7 @@ If during any stage the agent discovers evidence that contradicts the initial Ph
 2. If flow state is missing → guide the user to run \`npx cclaw-cli init\` and stop.
 3. If flow state is only a fresh init placeholder (\`completedStages: []\`, all \`passed\` arrays empty, and no \`00-idea.md\`) → stop and ask for \`/cc <prompt>\` to start a tracked run. Do not create a brainstorm state implicitly.
 4. Otherwise check current stage gates, resume if incomplete, and advance if complete.
+5. **TDD wave dispatch (v6.13.1):** When \`currentStage\` is \`tdd\`, read \`${RUNTIME_ROOT}/artifacts/05-plan.md\` Parallel Execution Plan block and \`${RUNTIME_ROOT}/artifacts/wave-plans/\` **before** any slice-routing question. If an open wave still has multiple ready slices, resume parallel dispatch for the **remaining** members only (do not restart completed slices).
 
 ## Headless mode (CI/automation only)
 
@@ -207,9 +208,11 @@ Progress the tracked flow only when one exists:
 2. If missing, guide the user to run \`npx cclaw-cli init\` and stop.
 3. If it is only a fresh init placeholder (\`completedStages: []\`, no passed gates, and no \`${RUNTIME_ROOT}/artifacts/00-idea.md\`), stop and ask for \`/cc <prompt>\` to start a tracked run. Do not silently create a brainstorm run.
 4. Check gates for \`currentStage\`.
-5. If incomplete → load current stage skill and execute.
-6. If complete → advance to next stage and execute.
-7. If flow is done → report completion.
+5. **TDD (v6.13.1):** When \`currentStage\` is \`tdd\`, read \`${RUNTIME_ROOT}/artifacts/05-plan.md\` (managed \`## Parallel Execution Plan\` between \`parallel-exec-managed\` markers) and scan \`${RUNTIME_ROOT}/artifacts/wave-plans/wave-NN.md\` **before** asking which slice runs next. Merge sources in controller memory: Parallel Execution Plan first, wave files second; the same slice must not disagree across sources.
+6. **Wave dispatch resume:** If a wave is partially closed (some members already past GREEN/REFACTOR), continue with the remaining members in parallel; never redo finished lanes.
+7. If incomplete → load current stage skill and execute.
+8. If complete → advance to next stage and execute.
+9. If flow is done → report completion.
 
 ## Public flow habit
 

package/dist/delegation.d.ts

@@ -2,6 +2,7 @@ import { type SubagentFallback } from "./harness-adapters.js";
 import { type MandatoryDelegationTaskClass } from "./content/stage-schema.js";
 import type { FlowStage } from "./types.js";
 import { type FlowState } from "./flow-state.js";
+import { type ParseImplementationUnitParallelOptions, type ParsedParallelWave } from "./internal/plan-split-waves.js";
 export type DelegationMode = "mandatory" | "proactive";
 export type DelegationStatus = "scheduled" | "launched" | "acknowledged" | "completed" | "failed" | "waived" | "stale";
 export declare const DELEGATION_DISPATCH_SURFACES: readonly ["claude-task", "cursor-task", "opencode-agent", "codex-agent", "generic-task", "role-switch", "manual"];
@@ -390,6 +391,14 @@ export interface SelectReadySlicesOptions {
  * `claimedPaths` intersections with already-selected units and active holders.
  */
 export declare function selectReadySlices(units: ReadySliceUnit[], opts: SelectReadySlicesOptions): ReadySliceUnit[];
+/**
+ * v6.13.1 — build scheduler rows from merged parallel wave definitions + plan units.
+ */
+export declare function readySliceUnitsFromMergedWaves(mergedWaves: ParsedParallelWave[], planMarkdown: string, options?: ParseImplementationUnitParallelOptions): ReadySliceUnit[];
+/**
+ * v6.13.1 — load merged wave plan (Parallel Execution Plan block + wave-plans/) and map to `ReadySliceUnit[]`.
+ */
+export declare function loadTddReadySlicePool(planMarkdown: string, artifactsDir: string, options?: ParseImplementationUnitParallelOptions): Promise<ReadySliceUnit[]>;
 /**
  * v6.10.0 (P1) — when scheduling a `slice-implementer` on a TDD stage,
  * compare `claimedPaths` against every currently active span on the

package/dist/delegation.js

@@ -9,7 +9,7 @@ import { HARNESS_ADAPTERS } from "./harness-adapters.js";
 import { readFlowState } from "./runs.js";
 import { mandatoryAgentsFor, stageSchema } from "./content/stage-schema.js";
 import { effectiveWorktreeExecutionMode } from "./flow-state.js";
-import { compareCanonicalUnitIds } from "./internal/plan-split-waves.js";
+import { compareCanonicalUnitIds, mergeParallelWaveDefinitions, parseImplementationUnitParallelFields, parseImplementationUnits, parseParallelExecutionPlanWaves, parseWavePlanDirectory } from "./internal/plan-split-waves.js";
 const execFileAsync = promisify(execFile);
 const TERMINAL_DELEGATION_STATUSES = new Set(["completed", "failed", "waived", "stale"]);
 export const DELEGATION_DISPATCH_SURFACES = [
@@ -730,6 +730,54 @@ export function selectReadySlices(units, opts) {
     }
     return selected;
 }
+/**
+ * v6.13.1 — build scheduler rows from merged parallel wave definitions + plan units.
+ */
+export function readySliceUnitsFromMergedWaves(mergedWaves, planMarkdown, options) {
+    const units = parseImplementationUnits(planMarkdown);
+    const metaByUnit = new Map(units.map((u) => {
+        const m = parseImplementationUnitParallelFields(u, options);
+        return [m.unitId, m];
+    }));
+    const sliceSet = new Set();
+    for (const w of mergedWaves) {
+        for (const m of w.members) {
+            sliceSet.add(m.sliceId);
+        }
+    }
+    const out = [];
+    for (const sliceId of [...sliceSet].sort((a, b) => a.localeCompare(b))) {
+        const member = mergedWaves.flatMap((w) => w.members).find((x) => x.sliceId === sliceId);
+        if (!member)
+            continue;
+        const meta = metaByUnit.get(member.unitId);
+        if (!meta) {
+            out.push({
+                unitId: member.unitId,
+                sliceId,
+                dependsOn: [],
+                claimedPaths: [],
+                parallelizable: true
+            });
+            continue;
+        }
+        out.push({
+            unitId: meta.unitId,
+            sliceId,
+            dependsOn: meta.dependsOn,
+            claimedPaths: meta.claimedPaths,
+            parallelizable: meta.parallelizable
+        });
+    }
+    return out;
+}
+/**
+ * v6.13.1 — load merged wave plan (Parallel Execution Plan block + wave-plans/) and map to `ReadySliceUnit[]`.
+ */
+export async function loadTddReadySlicePool(planMarkdown, artifactsDir, options) {
+    const merged = mergeParallelWaveDefinitions(parseParallelExecutionPlanWaves(planMarkdown), await parseWavePlanDirectory(artifactsDir));
+    return readySliceUnitsFromMergedWaves(merged, planMarkdown, options);
+}
 function readMaxParallelOverrideFromEnv() {
     const raw = process.env.CCLAW_MAX_PARALLEL_SLICE_IMPLEMENTERS;
     if (typeof raw !== "string" || raw.trim().length === 0)

package/dist/install.js

@@ -25,7 +25,7 @@ import { LANGUAGE_RULE_PACK_DIR, LEGACY_LANGUAGE_RULE_PACK_FOLDERS } from "./con
 import { RESEARCH_PLAYBOOKS } from "./content/research-playbooks.js";
 import { SUBAGENT_CONTEXT_SKILLS } from "./content/subagent-context-skills.js";
 import { CCLAW_AGENTS } from "./content/core-agents.js";
-import { createInitialFlowState } from "./flow-state.js";
+import { createInitialFlowState, effectiveWorktreeExecutionMode } from "./flow-state.js";
 import { ensureDir, exists, writeFileSafe } from "./fs-utils.js";
 import { ManagedResourceSession, setActiveManagedResourceSession } from "./managed-resources.js";
 import { ensureGitignore, removeGitignorePatterns } from "./gitignore.js";
@@ -34,7 +34,7 @@ import { validateHookDocument } from "./hook-schema.js";
 import { detectHarnesses } from "./init-detect.js";
 import { classifyCodexHooksFlag, codexConfigPath, readCodexConfig } from "./codex-feature-flag.js";
 import { CorruptFlowStateError, ensureRunSystem, readFlowState, writeFlowState } from "./runs.js";
-import { PLAN_SPLIT_DEFAULT_WAVE_SIZE, buildParallelExecutionPlanSection, planArtifactLacksV613ParallelMetadata, upsertParallelExecutionPlanSection } from "./internal/plan-split-waves.js";
+import { PLAN_SPLIT_DEFAULT_WAVE_SIZE, buildParallelExecutionPlanSection, formatNextParallelWaveSyncHint, mergeParallelWaveDefinitions, parseParallelExecutionPlanWaves, parseWavePlanDirectory, planArtifactLacksV613ParallelMetadata, upsertParallelExecutionPlanSection } from "./internal/plan-split-waves.js";
 import { FLOW_STAGES } from "./types.js";
 const OPENCODE_PLUGIN_REL_PATH = ".opencode/plugins/cclaw-plugin.mjs";
 const CURSOR_RULE_REL_PATH = ".cursor/rules/cclaw-workflow.mdc";
@@ -1135,6 +1135,28 @@ async function assertExpectedHarnessShims(projectRoot, harnesses) {
         }
     }
 }
+async function maybeLogParallelWaveDispatchHint(projectRoot) {
+    const flowPath = runtimePath(projectRoot, "state", "flow-state.json");
+    if (!(await exists(flowPath)))
+        return;
+    try {
+        const state = await readFlowState(projectRoot);
+        if (effectiveWorktreeExecutionMode(state) !== "worktree-first")
+            return;
+        const planPath = runtimePath(projectRoot, "artifacts", "05-plan.md");
+        if (!(await exists(planPath)))
+            return;
+        const planRaw = await fs.readFile(planPath, "utf8");
+        const merged = mergeParallelWaveDefinitions(parseParallelExecutionPlanWaves(planRaw), await parseWavePlanDirectory(runtimePath(projectRoot, "artifacts")));
+        const hint = formatNextParallelWaveSyncHint(merged);
+        if (hint) {
+            process.stdout.write(`cclaw: ${hint}\n`);
+        }
+    }
+    catch {
+        // best-effort note only
+    }
+}
 async function materializeRuntime(projectRoot, config, forceStateReset, operation = "sync") {
     await warnStaleInitSentinel(projectRoot, operation);
     const sentinelPath = await writeInitSentinel(projectRoot, operation);
@@ -1175,6 +1197,9 @@ async function materializeRuntime(projectRoot, config, forceStateReset, operatio
         await assertExpectedHarnessShims(projectRoot, harnesses);
         await writeCursorWorkflowRule(projectRoot, harnesses);
         await ensureGitignore(projectRoot);
+        if (operation === "sync" || operation === "upgrade") {
+            await maybeLogParallelWaveDispatchHint(projectRoot);
+        }
         await managedSession.commit();
         await fs.unlink(sentinelPath).catch(() => undefined);
     }

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

@@ -31,6 +31,52 @@ export interface PlanSplitWavesArgs {
 }
 export declare const PLAN_SPLIT_DEFAULT_WAVE_SIZE = 5;
 export declare const PLAN_SPLIT_SMALL_PLAN_THRESHOLD = 50;
+/** v6.13.1 — member line in Parallel Execution Plan or wave-NN.md */
+export interface ParsedParallelWaveMember {
+    sliceId: string;
+    unitId: string;
+}
+export interface ParsedParallelWave {
+    waveId: string;
+    members: ParsedParallelWaveMember[];
+}
+export declare class WavePlanDuplicateSliceError extends Error {
+    constructor(message: string);
+}
+export declare class WavePlanMergeConflictError extends Error {
+    constructor(message: string);
+}
+/**
+ * Raw body between parallel execution managed markers (no markers included).
+ */
+export declare function extractParallelExecutionManagedBody(planMarkdown: string): string | null;
+/**
+ * Members list after `Members:` in Parallel Execution Plan / wave-NN headers.
+ * Supports markdown bold `**Members:**` (colon between Members and closing `**`)
+ * and plain `Members:`.
+ */
+export declare function extractMembersListFromLine(trimmedLine: string): string | null;
+/**
+ * Parse `## Parallel Execution Plan` managed block for wave headings and Members lines.
+ * Malformed member tokens are skipped. Duplicate slice ids in one plan source throw.
+ */
+export declare function parseParallelExecutionPlanWaves(planMarkdown: string): ParsedParallelWave[];
+/**
+ * Parse a single wave-NN.md: prefer a `Members:` line in the header; otherwise
+ * collect distinct S-N tokens in the first lines (legacy).
+ */
+export declare function parseWavePlanFileBody(body: string, waveId: string): ParsedParallelWave;
+export declare function parseWavePlanDirectory(artifactsDir: string): Promise<ParsedParallelWave[]>;
+/**
+ * Merge wave definitions: managed Parallel Execution Plan first, then wave-NN.md.
+ * Same slice must map to the same wave id and unit id in both sources or a
+ * `WavePlanMergeConflictError` is thrown.
+ */
+export declare function mergeParallelWaveDefinitions(primary: ParsedParallelWave[], secondary: ParsedParallelWave[]): ParsedParallelWave[];
+/**
+ * One-line operator hint after sync when a multi-member wave exists.
+ */
+export declare function formatNextParallelWaveSyncHint(merged: ParsedParallelWave[]): string | null;
 export interface ParsedImplementationUnit {
     id: string;
     /**

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

@@ -10,6 +10,215 @@ 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 -->";
+export class WavePlanDuplicateSliceError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "WavePlanDuplicateSliceError";
+    }
+}
+export class WavePlanMergeConflictError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "WavePlanMergeConflictError";
+    }
+}
+/**
+ * Raw body between parallel execution managed markers (no markers included).
+ */
+export function extractParallelExecutionManagedBody(planMarkdown) {
+    const startIdx = planMarkdown.indexOf(PARALLEL_EXEC_MANAGED_START);
+    const endIdx = planMarkdown.indexOf(PARALLEL_EXEC_MANAGED_END);
+    if (startIdx < 0 || endIdx <= startIdx)
+        return null;
+    return planMarkdown.slice(startIdx + PARALLEL_EXEC_MANAGED_START.length, endIdx).trim();
+}
+function tokenToSliceAndUnit(token) {
+    const t = token.trim().replace(/^[`"'[\]()]+|[`"'[\]()]+$/gu, "");
+    const u = /^U-(\d+)$/u.exec(t);
+    if (u) {
+        const n = u[1];
+        return { unitId: `U-${n}`, sliceId: `S-${n}` };
+    }
+    const s = /^S-(\d+)$/u.exec(t);
+    if (s) {
+        const n = s[1];
+        return { unitId: `U-${n}`, sliceId: `S-${n}` };
+    }
+    return null;
+}
+/**
+ * Members list after `Members:` in Parallel Execution Plan / wave-NN headers.
+ * Supports markdown bold `**Members:**` (colon between Members and closing `**`)
+ * and plain `Members:`.
+ */
+export function extractMembersListFromLine(trimmedLine) {
+    const bold = /^[-*]?\s*\*\*Members:\*\*\s*(.+)$/iu.exec(trimmedLine);
+    if (bold)
+        return bold[1].trim();
+    const plain = /^[-*]?\s*Members\s*:\s*(.+)$/iu.exec(trimmedLine);
+    if (plain)
+        return plain[1].trim();
+    return null;
+}
+/**
+ * Parse `## Parallel Execution Plan` managed block for wave headings and Members lines.
+ * Malformed member tokens are skipped. Duplicate slice ids in one plan source throw.
+ */
+export function parseParallelExecutionPlanWaves(planMarkdown) {
+    const body = extractParallelExecutionManagedBody(planMarkdown);
+    if (!body)
+        return [];
+    const lines = body.split(/\r?\n/u);
+    const waves = [];
+    let current = null;
+    const seenSlices = new Set();
+    const flushCurrent = () => {
+        if (current && current.members.length > 0) {
+            waves.push(current);
+        }
+    };
+    for (const rawLine of lines) {
+        const trimmed = rawLine.trim();
+        const waveMatch = /^###\s+Wave\s+(\d+)\s*$/iu.exec(trimmed);
+        if (waveMatch) {
+            flushCurrent();
+            const n = waveMatch[1];
+            current = { waveId: `W-${n.padStart(2, "0")}`, members: [] };
+            continue;
+        }
+        const membersCsv = extractMembersListFromLine(trimmed);
+        if (membersCsv !== null && current) {
+            const parts = membersCsv
+                .split(/,/u)
+                .map((p) => p.trim())
+                .filter((p) => p.length > 0);
+            for (const part of parts) {
+                const ids = tokenToSliceAndUnit(part);
+                if (!ids)
+                    continue;
+                if (seenSlices.has(ids.sliceId)) {
+                    throw new WavePlanDuplicateSliceError(`duplicate slice ${ids.sliceId} in Parallel Execution Plan managed block`);
+                }
+                seenSlices.add(ids.sliceId);
+                current.members.push(ids);
+            }
+        }
+    }
+    flushCurrent();
+    return waves;
+}
+/**
+ * Parse a single wave-NN.md: prefer a `Members:` line in the header; otherwise
+ * collect distinct S-N tokens in the first lines (legacy).
+ */
+export function parseWavePlanFileBody(body, waveId) {
+    const members = [];
+    const seen = new Set();
+    const headLines = body.split(/\r?\n/u).slice(0, 120);
+    let membersCsv = null;
+    for (const raw of headLines) {
+        membersCsv = extractMembersListFromLine(raw.trim());
+        if (membersCsv !== null)
+            break;
+    }
+    if (membersCsv !== null) {
+        for (const part of membersCsv.split(/,/u)) {
+            const ids = tokenToSliceAndUnit(part);
+            if (!ids)
+                continue;
+            if (seen.has(ids.sliceId)) {
+                throw new WavePlanDuplicateSliceError(`duplicate slice ${ids.sliceId} in ${waveId} wave file`);
+            }
+            seen.add(ids.sliceId);
+            members.push(ids);
+        }
+    }
+    if (members.length === 0) {
+        const regex = /\b(S-\d+)\b/gu;
+        let match;
+        while ((match = regex.exec(body)) !== null) {
+            const ids = tokenToSliceAndUnit(match[1]);
+            if (!ids)
+                continue;
+            if (seen.has(ids.sliceId))
+                continue;
+            seen.add(ids.sliceId);
+            members.push(ids);
+        }
+    }
+    return { waveId, members };
+}
+export async function parseWavePlanDirectory(artifactsDir) {
+    const wavePlansDir = path.join(artifactsDir, "wave-plans");
+    let entries = [];
+    try {
+        entries = await fs.readdir(wavePlansDir);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of [...entries].sort()) {
+        const match = /^wave-(\d+)\.md$/u.exec(name);
+        if (!match)
+            continue;
+        const waveId = `W-${match[1].padStart(2, "0")}`;
+        const body = await fs.readFile(path.join(wavePlansDir, name), "utf8");
+        const wave = parseWavePlanFileBody(body, waveId);
+        if (wave.members.length > 0) {
+            out.push(wave);
+        }
+    }
+    return out;
+}
+/**
+ * Merge wave definitions: managed Parallel Execution Plan first, then wave-NN.md.
+ * Same slice must map to the same wave id and unit id in both sources or a
+ * `WavePlanMergeConflictError` is thrown.
+ */
+export function mergeParallelWaveDefinitions(primary, secondary) {
+    const byWave = new Map();
+    const sliceBinding = new Map();
+    const addWaves = (waves) => {
+        for (const wave of waves) {
+            let memMap = byWave.get(wave.waveId);
+            if (!memMap) {
+                memMap = new Map();
+                byWave.set(wave.waveId, memMap);
+            }
+            for (const member of wave.members) {
+                const prev = sliceBinding.get(member.sliceId);
+                if (prev) {
+                    if (prev.waveId !== wave.waveId || prev.unitId !== member.unitId) {
+                        throw new WavePlanMergeConflictError(`slice ${member.sliceId}: conflicting wave plan sources (wave ${prev.waveId} vs ${wave.waveId}, unit ${prev.unitId} vs ${member.unitId})`);
+                    }
+                }
+                else {
+                    sliceBinding.set(member.sliceId, { waveId: wave.waveId, unitId: member.unitId });
+                }
+                memMap.set(member.sliceId, member);
+            }
+        }
+    };
+    addWaves(primary);
+    addWaves(secondary);
+    return [...byWave.entries()]
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([wid, memMap]) => ({
+        waveId: wid,
+        members: [...memMap.values()].sort((p, q) => p.sliceId.localeCompare(q.sliceId))
+    }));
+}
+/**
+ * One-line operator hint after sync when a multi-member wave exists.
+ */
+export function formatNextParallelWaveSyncHint(merged) {
+    const candidate = merged.find((w) => w.members.length >= 2);
+    if (!candidate)
+        return null;
+    const ids = candidate.members.map((m) => m.sliceId).join(", ");
+    return `Parallel Execution Plan: ${candidate.waveId} has ${candidate.members.length} parallel members (${ids}).`;
+}
 /**
  * Parse v6.13 parallel-metadata bullets from an implementation unit body.
  * Missing keys use conservative defaults (`dependsOn: []`, `parallelizable: true`
@@ -18,12 +227,17 @@ const PARALLEL_EXEC_MANAGED_END = "<!-- parallel-exec-managed-end -->";
 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");
+        const esc = label.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+        const bold = new RegExp(`^[-*]\\s*\\*\\*${esc}:\\*\\*\\s*(.*)$`, "imu");
+        const legacy = new RegExp(`^[-*]\\s*\\*{0,2}${esc}\\*{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();
+            const mb = bold.exec(line);
+            if (mb)
+                return mb[1]?.trim();
+            const ml = legacy.exec(line);
+            if (ml)
+                return ml[1]?.trim();
         }
         return undefined;
     };
@@ -53,8 +267,13 @@ export function parseImplementationUnitParallelFields(unit, options) {
     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()));
+    const esc = label.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+    const bold = new RegExp(`^[-*]\\s*\\*\\*${esc}:\\*\\*`, "imu");
+    const legacy = new RegExp(`^[-*]\\s*\\*{0,2}${esc}\\*{0,2}\\s*:`, "imu");
+    return body.split(/\r?\n/u).some((raw) => {
+        const line = raw.trim();
+        return bold.test(line) || legacy.test(line);
+    });
 }
 /**
  * True when the plan has implementation units but any unit is missing v6.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cclaw-cli",
-  "version": "6.13.0",
+  "version": "6.13.1",
   "description": "Installer-first flow toolkit for coding agents",
   "type": "module",
   "bin": {