cclaw-cli 6.9.0 → 6.11.0

package/dist/content/templates.js

@@ -976,41 +976,32 @@ ${renderBehaviorAnchorTemplateLine("tdd")}
 - Open questions:
 - Drift from upstream (or \`None\`):
 
+<!-- auto-start: slices-index -->
+## Slices Index
+
+_Auto-rendered from \`tdd-slices/S-*.md\` once slice-documenter or controller writes per-slice files. Do not edit by hand._
+<!-- auto-end: slices-index -->
+
 ## Test Discovery
-| Slice | Existing tests / helpers / fixtures | Exact command(s) | Pattern to extend |
-|---|---|---|---|
-| S-1 |  |  |  |
+> Overall narrative for how this stage discovered the existing test surface. Per-slice details live in \`tdd-slices/S-<id>.md\`.
 
 ## System-Wide Impact Check
 | Slice | Callbacks/state/interfaces/contracts affected | Coverage decision |
 |---|---|---|
 | S-1 |  | covered/out-of-scope because  |
 
-## Execution Posture
-- Posture: sequential | dependency-batched | blocked
-- Vertical-slice RED/GREEN/REFACTOR checkpoint plan:
-- Incremental commits: yes/no/deferred because
-
 ## RED Evidence
-| Slice | Test name | Command | Failure output summary |
-|---|---|---|---|
-| S-1 |  |  |  |
+> From v6.11.0 the per-slice RED rows are auto-satisfied by \`phase=red\` events in \`delegation-events.jsonl\` (controller dispatches \`test-author --slice S-<id> --phase red\`). Legacy hand-filled tables continue to validate as a fallback. Use \`Evidence: <path>\` or \`Evidence: spanId:<id>\` pointers if you prefer a manual reference.
 
-## Acceptance Mapping
-| Vertical slice | Source item ID | Spec criterion ID |
-|---|---|---|
-| S-1 | SRC-1 | AC-1 |
-
-> Map each slice to the active track's source item: plan slice on standard/medium, or the \`Quick Reproduction Contract\` bug slice / spec acceptance item on quick.
+## Acceptance & Failure Map
+| Slice | Source ID | AC ID | Expected behavior | RED-link |
+|---|---|---|---|---|
+| S-1 | SRC-1 | AC-1 |  |  |
 
-## Failure Analysis
-| Slice | Expected missing behavior | Actual failure reason |
-|---|---|---|
-| S-1 |  |  |
+> Each slice maps to the active track's source item (plan slice on standard/medium, or the \`Quick Reproduction Contract\` bug slice / spec acceptance item on quick) and to a spec criterion. The RED-link column is satisfied by either a \`spanId:<id>\` from the delegation ledger or an \`<artifacts-dir>/<file>\` evidence pointer. From v6.11.0 the column is auto-derivable: a \`phase=red\` event in \`delegation-events.jsonl\` with non-empty evidenceRefs auto-satisfies the row.
 
 ## GREEN Evidence
-- Full suite command:
-- Full suite result:
+> From v6.11.0 GREEN rows are auto-satisfied by \`phase=green\` events in \`delegation-events.jsonl\` (controller dispatches \`slice-implementer --slice S-<id> --phase green\`). Legacy hand-filled tables continue to validate as a fallback. Use \`Evidence: <path>\` or \`Evidence: spanId:<id>\` pointers if you prefer a manual reference.
 
 ## REFACTOR Notes
 - What changed:
@@ -1027,19 +1018,11 @@ ${renderBehaviorAnchorTemplateLine("tdd")}
 - Acknowledged: yes — code that landed before its test will be deleted and rewritten from the test.
 - Exceptions invoked (or \`- None.\`):
 
-## Watched-RED Proof
-> Required for every new test in this stage. Each row proves the test was *observed* failing before any production code was written.
-
-| Slice | Test name | Observed at (ISO ts) | Failure reason snippet | Source command/log |
-|---|---|---|---|---|
-| S-1 |  |  |  |  |
-
+<!-- auto-start: tdd-slice-summary -->
 ## Vertical Slice Cycle
-> Per slice: RED -> GREEN -> REFACTOR within the same cycle (refactor not deferred). The linter checks structural presence of all three phases.
 
-| Slice | RED ts | GREEN ts | REFACTOR ts (or \`deferred because <reason>\`) |
-|---|---|---|---|
-| S-1 |  |  |  |
+_Auto-rendered from \`delegation-events.jsonl\` once \`test-author\` and \`slice-implementer\` are dispatched with \`--slice <id> --phase red|green|refactor|refactor-deferred\`. Do not edit by hand._
+<!-- auto-end: tdd-slice-summary -->
 
 ## Assertion Correctness Notes
 > For each new test assertion, name a *plausible subtle bug* that would still pass it (mental mutation test). If you cannot, the assertion is too coarse — strengthen it.
@@ -1633,6 +1616,31 @@ Track-specific skips are allowed only when \`flow-state.track\` + \`skippedStage
 - Preamble budget: keep role/status announcements brief and avoid repeating
   them unless the stage or role changes.
 `;
+/**
+ * v6.11.0 (S2) — per-slice prose file written by `slice-documenter`
+ * (or the controller) to `<artifacts-dir>/tdd-slices/S-<id>.md`. The
+ * main `06-tdd.md` is auto-indexed via `## Slices Index`.
+ */
+export function tddSliceFileTemplate(sliceId) {
+    return `# Slice ${sliceId}
+
+## Plan unit
+T-...
+
+## Acceptance criteria
+AC-...
+
+## Why this slice
+
+## What was tested
+
+## What was implemented
+
+## REFACTOR notes
+
+## Learnings
+`;
+}
 export function buildRulesJson() {
     return {
         version: 1,

package/dist/delegation.d.ts

@@ -129,7 +129,45 @@ export type DelegationEntry = {
      * coherent successor chain.
      */
     supersededBy?: string;
+    /**
+     * v6.10.0 (P1) — repo-relative paths the delegated unit will edit.
+     * Used by the slice-implementer file-overlap scheduler to either
+     * auto-allow parallel dispatch (disjoint paths) or block the row
+     * with `DispatchOverlapError` (overlapping paths). For agents
+     * other than slice-implementer the field is advisory.
+     *
+     * keep in sync with the inline copy in
+     * `src/content/hooks.ts::delegationRecordScript`.
+     */
+    claimedPaths?: string[];
+    /**
+     * v6.11.0 (D1) — TDD slice identifier, e.g. `"S-1"`. Recorded by the
+     * controller when dispatching `test-author` / `slice-implementer` /
+     * `slice-documenter` so the artifact linter can auto-derive the
+     * Watched-RED Proof + Vertical Slice Cycle tables from
+     * `delegation-events.jsonl` instead of requiring agents to maintain
+     * the markdown by hand. Optional: legacy and non-TDD rows omit it.
+     *
+     * keep in sync with the inline copy in
+     * `src/content/hooks.ts::delegationRecordScript`.
+     */
+    sliceId?: string;
+    /**
+     * v6.11.0 (D1) — explicit phase tag for TDD slice events. Combined
+     * with `sliceId`, the linter validates RED -> GREEN -> REFACTOR
+     * monotonicity per slice. `refactor-deferred` requires a rationale
+     * either via `--refactor-rationale` (recorded into evidenceRefs[0])
+     * or an `evidenceRefs` entry that contains the rationale text.
+     * `doc` is reserved for the parallel `slice-documenter` subagent
+     * (Phase C). Optional: legacy and non-TDD rows omit it.
+     *
+     * keep in sync with the inline copy in
+     * `src/content/hooks.ts::delegationRecordScript`.
+     */
+    phase?: "red" | "green" | "refactor" | "refactor-deferred" | "doc";
 };
+export declare const DELEGATION_PHASES: readonly ["red", "green", "refactor", "refactor-deferred", "doc"];
+export type DelegationPhase = (typeof DELEGATION_PHASES)[number];
 export declare const DELEGATION_LEDGER_SCHEMA_VERSION: 3;
 export type DelegationLedger = {
     runId: string;
@@ -231,6 +269,87 @@ export declare class DispatchDuplicateError extends Error {
         };
     });
 }
+/**
+ * v6.10.0 (P1) — thrown by `validateFileOverlap` when a new
+ * `slice-implementer` is scheduled on a TDD stage with at least one
+ * `claimedPaths` entry that overlaps an active span. The cclaw scheduler
+ * auto-allows parallel dispatch when paths are disjoint, so an explicit
+ * overlap is treated as a serialization signal: the operator must wait
+ * for the existing span to terminate or pass `--allow-parallel`
+ * deliberately to acknowledge the conflict.
+ */
+export declare class DispatchOverlapError extends Error {
+    readonly existingSpanId: string;
+    readonly newSpanId: string;
+    readonly pair: {
+        stage: string;
+        agent: string;
+    };
+    readonly conflictingPaths: string[];
+    constructor(params: {
+        existingSpanId: string;
+        newSpanId: string;
+        pair: {
+            stage: string;
+            agent: string;
+        };
+        conflictingPaths: string[];
+    });
+}
+/**
+ * v6.10.0 (P2) — thrown when the count of active `slice-implementer`
+ * spans (after fold) reaches `MAX_PARALLEL_SLICE_IMPLEMENTERS` and a new
+ * scheduled row would push it past the cap. Cap can be overridden once
+ * via `--override-cap=N` on the hook flag or globally via
+ * `CCLAW_MAX_PARALLEL_SLICE_IMPLEMENTERS=<N>` env.
+ */
+export declare class DispatchCapError extends Error {
+    readonly cap: number;
+    readonly active: number;
+    readonly pair: {
+        stage: string;
+        agent: string;
+    };
+    constructor(params: {
+        cap: number;
+        active: number;
+        pair: {
+            stage: string;
+            agent: string;
+        };
+    });
+}
+/**
+ * v6.10.0 (P2) — default cap on active `slice-implementer` spans in a
+ * single TDD run. Aligned with evanflow's parallel cap. Override via
+ * `CCLAW_MAX_PARALLEL_SLICE_IMPLEMENTERS=<int>` (validated `>=1`).
+ */
+export declare const MAX_PARALLEL_SLICE_IMPLEMENTERS: 5;
+/**
+ * v6.10.0 (P1) — when scheduling a `slice-implementer` on a TDD stage,
+ * compare `claimedPaths` against every currently active span on the
+ * same `(stage, agent)` pair. Overlap → throw `DispatchOverlapError`;
+ * disjoint paths → return `{ autoParallel: true }` so the caller can
+ * mark the new entry `allowParallel = true` without explicit operator
+ * intent. When the agent is not a slice-implementer or no
+ * `claimedPaths` are supplied, the function returns
+ * `{ autoParallel: false }` and the legacy dedup path takes over.
+ */
+export declare function validateFileOverlap(stamped: DelegationEntry, activeEntries: DelegationEntry[]): {
+    autoParallel: boolean;
+};
+/**
+ * v6.10.0 (P2) — enforce the slice-implementer fan-out cap. The new
+ * scheduled row pushes the active count from N to N+1; if that would
+ * exceed the cap (default 5, env-overridable), throw `DispatchCapError`.
+ *
+ * Caller passes the already-folded list of active entries (latest row
+ * per spanId, ACTIVE statuses only). The function counts entries that
+ * match the agent on the same `stage`. The new row's own spanId is
+ * excluded so re-recording a `scheduled` doesn't trip the cap on a
+ * span that's already counted.
+ */
+export declare function validateFanOutCap(stamped: DelegationEntry, activeEntries: DelegationEntry[], override?: number | null): void;
 /**
  * v6.9.0 — find the latest active span for a given `(stage, agent)`
  * pair in the supplied ledger entries. Returns the row whose latest

package/dist/delegation.js

@@ -38,6 +38,13 @@ export const DELEGATION_DISPATCH_SURFACE_PATH_PREFIXES = {
     "role-switch": [],
     "manual": []
 };
+export const DELEGATION_PHASES = [
+    "red",
+    "green",
+    "refactor",
+    "refactor-deferred",
+    "doc"
+];
 export const DELEGATION_LEDGER_SCHEMA_VERSION = 3;
 function delegationLogPath(projectRoot) {
     return path.join(projectRoot, RUNTIME_ROOT, "state", "delegation-log.json");
@@ -224,7 +231,14 @@ function isDelegationEntry(value) {
         (o.skill === undefined || typeof o.skill === "string") &&
         (o.schemaVersion === undefined || o.schemaVersion === 1 || o.schemaVersion === 2 || o.schemaVersion === 3) &&
         (o.allowParallel === undefined || typeof o.allowParallel === "boolean") &&
-        (o.supersededBy === undefined || typeof o.supersededBy === "string"));
+        (o.supersededBy === undefined || typeof o.supersededBy === "string") &&
+        (o.claimedPaths === undefined ||
+            (Array.isArray(o.claimedPaths) && o.claimedPaths.every((item) => typeof item === "string"))) &&
+        (o.sliceId === undefined ||
+            (typeof o.sliceId === "string" && o.sliceId.length > 0)) &&
+        (o.phase === undefined ||
+            (typeof o.phase === "string" &&
+                DELEGATION_PHASES.includes(o.phase))));
 }
 function isDelegationDispatchSurface(value) {
     return typeof value === "string" && DELEGATION_DISPATCH_SURFACES.includes(value);
@@ -547,6 +561,138 @@ export class DispatchDuplicateError extends Error {
         this.pair = params.pair;
     }
 }
+/**
+ * v6.10.0 (P1) — thrown by `validateFileOverlap` when a new
+ * `slice-implementer` is scheduled on a TDD stage with at least one
+ * `claimedPaths` entry that overlaps an active span. The cclaw scheduler
+ * auto-allows parallel dispatch when paths are disjoint, so an explicit
+ * overlap is treated as a serialization signal: the operator must wait
+ * for the existing span to terminate or pass `--allow-parallel`
+ * deliberately to acknowledge the conflict.
+ */
+export class DispatchOverlapError extends Error {
+    existingSpanId;
+    newSpanId;
+    pair;
+    conflictingPaths;
+    constructor(params) {
+        super(`dispatch_overlap — slice-implementer span ${params.newSpanId} claims path(s) ${params.conflictingPaths.join(", ")} already held by active spanId=${params.existingSpanId} on stage=${params.pair.stage}. ` +
+            `Wait for ${params.existingSpanId} to finish, dispatch a non-overlapping slice, or pass --allow-parallel to acknowledge the conflict.`);
+        this.name = "DispatchOverlapError";
+        this.existingSpanId = params.existingSpanId;
+        this.newSpanId = params.newSpanId;
+        this.pair = params.pair;
+        this.conflictingPaths = params.conflictingPaths;
+    }
+}
+/**
+ * v6.10.0 (P2) — thrown when the count of active `slice-implementer`
+ * spans (after fold) reaches `MAX_PARALLEL_SLICE_IMPLEMENTERS` and a new
+ * scheduled row would push it past the cap. Cap can be overridden once
+ * via `--override-cap=N` on the hook flag or globally via
+ * `CCLAW_MAX_PARALLEL_SLICE_IMPLEMENTERS=<N>` env.
+ */
+export class DispatchCapError extends Error {
+    cap;
+    active;
+    pair;
+    constructor(params) {
+        super(`dispatch_cap — ${params.active} active ${params.pair.agent}(s) at the cap of ${params.cap}. ` +
+            `Complete one before scheduling another, or pass --override-cap=N (or CCLAW_MAX_PARALLEL_SLICE_IMPLEMENTERS=N) to lift the cap for this run.`);
+        this.name = "DispatchCapError";
+        this.cap = params.cap;
+        this.active = params.active;
+        this.pair = params.pair;
+    }
+}
+/**
+ * v6.10.0 (P2) — default cap on active `slice-implementer` spans in a
+ * single TDD run. Aligned with evanflow's parallel cap. Override via
+ * `CCLAW_MAX_PARALLEL_SLICE_IMPLEMENTERS=<int>` (validated `>=1`).
+ */
+export const MAX_PARALLEL_SLICE_IMPLEMENTERS = 5;
+function readMaxParallelOverrideFromEnv() {
+    const raw = process.env.CCLAW_MAX_PARALLEL_SLICE_IMPLEMENTERS;
+    if (typeof raw !== "string" || raw.trim().length === 0)
+        return null;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || !Number.isInteger(parsed) || parsed < 1)
+        return null;
+    return parsed;
+}
+/**
+ * v6.10.0 (P1) — when scheduling a `slice-implementer` on a TDD stage,
+ * compare `claimedPaths` against every currently active span on the
+ * same `(stage, agent)` pair. Overlap → throw `DispatchOverlapError`;
+ * disjoint paths → return `{ autoParallel: true }` so the caller can
+ * mark the new entry `allowParallel = true` without explicit operator
+ * intent. When the agent is not a slice-implementer or no
+ * `claimedPaths` are supplied, the function returns
+ * `{ autoParallel: false }` and the legacy dedup path takes over.
+ */
+export function validateFileOverlap(stamped, activeEntries) {
+    if (stamped.agent !== "slice-implementer" || stamped.stage !== "tdd") {
+        return { autoParallel: false };
+    }
+    const newPaths = Array.isArray(stamped.claimedPaths) ? stamped.claimedPaths : [];
+    if (newPaths.length === 0) {
+        return { autoParallel: false };
+    }
+    const sameLane = activeEntries.filter((entry) => entry.stage === stamped.stage &&
+        entry.agent === stamped.agent &&
+        entry.spanId !== stamped.spanId);
+    if (sameLane.length === 0) {
+        return { autoParallel: true };
+    }
+    for (const existing of sameLane) {
+        const existingPaths = Array.isArray(existing.claimedPaths) ? existing.claimedPaths : [];
+        if (existingPaths.length === 0) {
+            // We can't prove disjoint without the other side declaring paths;
+            // be conservative and let the legacy dedup error path fire.
+            return { autoParallel: false };
+        }
+        const overlap = newPaths.filter((p) => existingPaths.includes(p));
+        if (overlap.length > 0) {
+            throw new DispatchOverlapError({
+                existingSpanId: existing.spanId ?? "unknown",
+                newSpanId: stamped.spanId ?? "unknown",
+                pair: { stage: stamped.stage, agent: stamped.agent },
+                conflictingPaths: overlap
+            });
+        }
+    }
+    return { autoParallel: true };
+}
+/**
+ * v6.10.0 (P2) — enforce the slice-implementer fan-out cap. The new
+ * scheduled row pushes the active count from N to N+1; if that would
+ * exceed the cap (default 5, env-overridable), throw `DispatchCapError`.
+ *
+ * Caller passes the already-folded list of active entries (latest row
+ * per spanId, ACTIVE statuses only). The function counts entries that
+ * match the agent on the same `stage`. The new row's own spanId is
+ * excluded so re-recording a `scheduled` doesn't trip the cap on a
+ * span that's already counted.
+ */
+export function validateFanOutCap(stamped, activeEntries, override) {
+    if (stamped.agent !== "slice-implementer" || stamped.stage !== "tdd")
+        return;
+    if (stamped.status !== "scheduled")
+        return;
+    const cap = (override !== null && override !== undefined && Number.isInteger(override) && override >= 1)
+        ? override
+        : (readMaxParallelOverrideFromEnv() ?? MAX_PARALLEL_SLICE_IMPLEMENTERS);
+    const sameLaneActive = activeEntries.filter((entry) => entry.stage === stamped.stage &&
+        entry.agent === stamped.agent &&
+        entry.spanId !== stamped.spanId);
+    if (sameLaneActive.length + 1 > cap) {
+        throw new DispatchCapError({
+            cap,
+            active: sameLaneActive.length,
+            pair: { stage: stamped.stage, agent: stamped.agent }
+        });
+    }
+}
 /**
  * v6.9.0 — find the latest active span for a given `(stage, agent)`
  * pair in the supplied ledger entries. Returns the row whose latest
@@ -657,15 +803,30 @@ export async function appendDelegation(projectRoot, entry) {
             return;
         }
         validateMonotonicTimestamps(stamped, prior.entries);
-        if (stamped.status === "scheduled" && stamped.allowParallel !== true) {
-            const existing = findActiveSpanForPair(stamped.stage, stamped.agent, activeRunId, prior);
-            if (existing && existing.spanId && existing.spanId !== stamped.spanId) {
-                throw new DispatchDuplicateError({
-                    existingSpanId: existing.spanId,
-                    existingStatus: existing.status,
-                    newSpanId: stamped.spanId,
-                    pair: { stage: stamped.stage, agent: stamped.agent }
-                });
+        if (stamped.status === "scheduled") {
+            // v6.10.0 (P1+P2): for slice-implementer rows with declared
+            // claimedPaths, the file-overlap scheduler runs first. Disjoint
+            // paths auto-promote the row to allowParallel so the legacy
+            // dispatch_duplicate guard does not fire. Overlapping paths
+            // throw DispatchOverlapError. The fan-out cap then runs against
+            // the active set (excluding the new row's spanId).
+            const sameRunPrior = prior.entries.filter((entry) => entry.runId === activeRunId);
+            const activeForRun = computeActiveSubagents(sameRunPrior);
+            const overlap = validateFileOverlap(stamped, activeForRun);
+            if (overlap.autoParallel && stamped.allowParallel !== true) {
+                stamped.allowParallel = true;
+            }
+            validateFanOutCap(stamped, activeForRun);
+            if (stamped.allowParallel !== true) {
+                const existing = findActiveSpanForPair(stamped.stage, stamped.agent, activeRunId, prior);
+                if (existing && existing.spanId && existing.spanId !== stamped.spanId) {
+                    throw new DispatchDuplicateError({
+                        existingSpanId: existing.spanId,
+                        existingStatus: existing.status,
+                        newSpanId: stamped.spanId,
+                        pair: { stage: stamped.stage, agent: stamped.agent }
+                    });
+                }
             }
         }
         await appendDelegationEvent(projectRoot, eventFromEntry(stamped));

package/dist/install.js

@@ -168,6 +168,14 @@ const DEPRECATED_STATE_FILES = [
     // now reads cycle phase progression directly from the artifact table.
     "tdd-cycle-log.jsonl"
 ];
+// v6.11.0 (R5): files under `<runtime>/artifacts/` that previous releases
+// generated and v6.11.0 removed. `cclaw-cli sync` deletes each so existing
+// installs lose the obsolete sidecar without requiring manual cleanup.
+const DEPRECATED_ARTIFACT_FILES = [
+    // v6.10.0 sidecar — replaced in v6.11.0 by phase events in
+    // delegation-events.jsonl + auto-rendered tables in 06-tdd.md.
+    "06-tdd-slices.jsonl"
+];
 const DEPRECATED_HOOK_FILES = [
     "observe.sh",
     "summarize-observations.sh",
@@ -851,6 +859,7 @@ async function cleanLegacyArtifacts(projectRoot) {
         ...DEPRECATED_COMMAND_FILES.map((file) => runtimePath(projectRoot, "commands", file)),
         ...DEPRECATED_SKILL_FILES.map((segments) => runtimePath(projectRoot, "skills", ...segments)),
         ...DEPRECATED_STATE_FILES.map((file) => runtimePath(projectRoot, "state", file)),
+        ...DEPRECATED_ARTIFACT_FILES.map((file) => runtimePath(projectRoot, "artifacts", file)),
         ...DEPRECATED_RUNTIME_ROOT_FILES.map((file) => runtimePath(projectRoot, file)),
         ...DEPRECATED_HOOK_FILES.map((file) => runtimePath(projectRoot, "hooks", file))
     ]) {

package/dist/internal/advance-stage.js

@@ -14,7 +14,8 @@ 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, DispatchDuplicateError } from "../delegation.js";
+import { DelegationTimestampError, DispatchCapError, DispatchDuplicateError, DispatchOverlapError } from "../delegation.js";
+import { parsePlanSplitWavesArgs, runPlanSplitWaves } from "./plan-split-waves.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
@@ -32,7 +33,7 @@ const GUARD_ENFORCED_SUBCOMMANDS = new Set([
 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\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\n");
         return 1;
     }
     try {
@@ -84,7 +85,10 @@ export async function runInternalCommand(projectRoot, argv, io) {
         if (subcommand === "waiver-grant") {
             return await runWaiverGrant(projectRoot, parseWaiverGrantArgs(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\n`);
+        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`);
         return 1;
     }
     catch (err) {
@@ -100,6 +104,14 @@ export async function runInternalCommand(projectRoot, argv, io) {
             io.stderr.write(`error: dispatch_duplicate — ${err.message}\n`);
             return 2;
         }
+        if (err instanceof DispatchOverlapError) {
+            io.stderr.write(`error: dispatch_overlap — ${err.message}\n`);
+            return 2;
+        }
+        if (err instanceof DispatchCapError) {
+            io.stderr.write(`error: dispatch_cap — ${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

@@ -0,0 +1,66 @@
+import type { Writable } from "node:stream";
+interface InternalIo {
+    stdout: Writable;
+    stderr: Writable;
+}
+/**
+ * v6.10.0 (P3) — split a large `05-plan.md` Implementation Units section
+ * into wave-NN.md sub-files so an executor can carry one wave at a time
+ * without re-reading the whole plan.
+ *
+ * Threshold contract:
+ *   - total units < SMALL_PLAN_THRESHOLD → no-op, exit 0.
+ *   - total units >= SMALL_PLAN_THRESHOLD → split into waves of `--wave-size`
+ *     (default 25).
+ *
+ * Files written:
+ *   - `<artifacts-dir>/wave-plans/wave-NN.md` per wave (1-indexed).
+ *   - In-place update to `05-plan.md` adding (or refreshing) a
+ *     `## Wave Plans` section between
+ *     `<!-- wave-split-managed-start -->` and `<!-- wave-split-managed-end -->`
+ *     markers. Outside-marker content is preserved verbatim.
+ *
+ * `--dry-run` prints the plan but does not write. `--force` overwrites
+ * existing wave files; without it, the command refuses to clobber.
+ */
+export interface PlanSplitWavesArgs {
+    waveSize: number;
+    dryRun: boolean;
+    force: boolean;
+    json: boolean;
+}
+export declare const PLAN_SPLIT_DEFAULT_WAVE_SIZE = 25;
+export declare const PLAN_SPLIT_SMALL_PLAN_THRESHOLD = 50;
+export interface ParsedImplementationUnit {
+    id: string;
+    /**
+     * The full markdown body of this unit, starting at the
+     * `### Implementation Unit U-N` heading and ending right before the
+     * next unit heading (or the next `## ` H2, or end of file).
+     */
+    body: string;
+    /** Repo-relative path declarations from the optional `Files:` line. */
+    paths: string[];
+}
+/**
+ * Parse `## Implementation Units` section into individual unit blocks.
+ * Recognizes the canonical heading shape in the TDD-velocity plan template
+ * (`### Implementation Unit U-<n>`). Tolerant of `Files:` listed either
+ * inline or as a `- **Files (...):**` bullet block.
+ */
+export declare function parseImplementationUnits(planMarkdown: string): ParsedImplementationUnit[];
+/**
+ * Pull repo-relative paths from a `Files:` line or the `Files (...)` bullet
+ * block. Both shapes appear in the wild; the parser extracts after the colon
+ * and splits on commas. Empty/whitespace items are dropped.
+ */
+export declare function extractPathsLine(unitBody: string): string[];
+export declare function parsePlanSplitWavesArgs(tokens: string[]): PlanSplitWavesArgs;
+/**
+ * Replace any existing managed Wave Plans block with the new one, or append
+ * it at the end of the file when no markers are present yet. The helper
+ * never touches text outside the markers.
+ */
+export declare function upsertWavePlansSection(planMarkdown: string, managedBlock: string): string;
+export declare function runPlanSplitWaves(projectRoot: string, args: PlanSplitWavesArgs, io: InternalIo): Promise<number>;
+export {};