cclaw-cli 6.9.0 → 6.10.0

package/dist/content/hooks.js

@@ -326,7 +326,7 @@ function hasPriorAck(events, args, runId) {
 function usage() {
   process.stderr.write([
     "Usage:",
-    "  node .cclaw/hooks/delegation-record.mjs --stage=<stage> --agent=<agent> --mode=<mandatory|proactive> --status=<scheduled|launched|acknowledged|completed|failed|waived|stale> --span-id=<id> [--dispatch-id=<id>] [--worker-run-id=<id>] [--dispatch-surface=<surface>] [--agent-definition-path=<path>] [--ack-ts=<iso>] [--launched-ts=<iso>] [--completed-ts=<iso>] [--evidence-ref=<ref>] [--waiver-reason=<text>] [--supersede=<prevSpanId>] [--allow-parallel] [--json]",
+    "  node .cclaw/hooks/delegation-record.mjs --stage=<stage> --agent=<agent> --mode=<mandatory|proactive> --status=<scheduled|launched|acknowledged|completed|failed|waived|stale> --span-id=<id> [--dispatch-id=<id>] [--worker-run-id=<id>] [--dispatch-surface=<surface>] [--agent-definition-path=<path>] [--ack-ts=<iso>] [--launched-ts=<iso>] [--completed-ts=<iso>] [--evidence-ref=<ref>] [--waiver-reason=<text>] [--supersede=<prevSpanId>] [--allow-parallel] [--paths=<comma-separated>] [--override-cap=<int>] [--json]",
     "  node .cclaw/hooks/delegation-record.mjs --rerecord --span-id=<id> --dispatch-id=<id> --dispatch-surface=<surface> --agent-definition-path=<path> [--ack-ts=<iso>] [--completed-ts=<iso>] [--evidence-ref=<ref>] [--json]",
     "  node .cclaw/hooks/delegation-record.mjs --repair --span-id=<id> --repair-reason=\"<why>\" [--json]",
     "",
@@ -339,6 +339,10 @@ function usage() {
     "Dispatch dedup (v6.8.0):",
     "  --supersede=<prevSpanId>  close the previous active span on this (stage, agent) as 'stale' before recording the new scheduled row",
     "  --allow-parallel          record both spans as concurrent; new row is tagged allowParallel: true",
+    "",
+    "TDD parallel scheduler (v6.10.0):",
+    "  --paths=<a,b,c>           repo-relative paths the slice-implementer will edit; disjoint sets auto-promote to allowParallel, overlap throws DispatchOverlapError",
+    "  --override-cap=<int>      raise the slice-implementer fan-out cap once for this dispatch (default cap " + String(5) + ", env CCLAW_MAX_PARALLEL_SLICE_IMPLEMENTERS overrides globally)",
     ""
   ].join("\\n") + "\\n");
 }
@@ -440,6 +444,13 @@ function buildRow(args, status, runId, now, options) {
   // Inherit the span's startTs from prior rows so monotonic validation
   // can compare against the original schedule, not the row write time.
   const startTs = (options && options.spanStartTs) || now;
+  // v6.10.0 (P1): claimedPaths from --paths=<comma-separated>. Empty
+  // arrays are dropped so the row stays compatible with v6.9 readers.
+  const claimedPathsRaw = typeof args.paths === "string" ? args.paths : "";
+  const claimedPaths = claimedPathsRaw
+    .split(",")
+    .map((value) => value.trim())
+    .filter((value) => value.length > 0);
   return {
     stage: args.stage,
     agent: args.agent,
@@ -461,7 +472,8 @@ function buildRow(args, status, runId, now, options) {
     completedTs: args["completed-ts"] || (status === "completed" ? now : undefined),
     endTs: TERMINAL.has(status) ? now : undefined,
     schemaVersion: LEDGER_SCHEMA_VERSION,
-    allowParallel: args["allow-parallel"] === true ? true : undefined
+    allowParallel: args["allow-parallel"] === true ? true : undefined,
+    claimedPaths: claimedPaths.length > 0 ? claimedPaths : undefined
   };
 }
 
@@ -502,6 +514,102 @@ function findActiveSpanForPairInline(stage, agent, runId, entries) {
   return null;
 }
 
+// keep in sync with computeActiveSubagents in src/delegation.ts
+function computeActiveSubagentsInline(entries) {
+  const ACTIVE_STATUSES = new Set(["scheduled", "launched", "acknowledged"]);
+  const effectiveTs = (entry) =>
+    entry.completedTs || entry.ackTs || entry.launchedTs || entry.endTs || entry.startTs || entry.ts || "";
+  const latestBySpan = new Map();
+  for (const entry of entries) {
+    if (!entry || typeof entry !== "object") continue;
+    if (typeof entry.spanId !== "string" || entry.spanId.length === 0) continue;
+    const existing = latestBySpan.get(entry.spanId);
+    if (!existing || effectiveTs(entry) >= effectiveTs(existing)) {
+      latestBySpan.set(entry.spanId, entry);
+    }
+  }
+  const active = [];
+  for (const entry of latestBySpan.values()) {
+    if (ACTIVE_STATUSES.has(entry.status)) active.push(entry);
+  }
+  return active;
+}
+
+// keep in sync with validateFileOverlap in src/delegation.ts
+function validateFileOverlapInline(stamped, activeEntries) {
+  if (stamped.agent !== "slice-implementer" || stamped.stage !== "tdd") {
+    return { autoParallel: false, conflict: null };
+  }
+  const newPaths = Array.isArray(stamped.claimedPaths) ? stamped.claimedPaths : [];
+  if (newPaths.length === 0) {
+    return { autoParallel: false, conflict: null };
+  }
+  const sameLane = activeEntries.filter(
+    (entry) =>
+      entry.stage === stamped.stage &&
+      entry.agent === stamped.agent &&
+      entry.spanId !== stamped.spanId
+  );
+  if (sameLane.length === 0) {
+    return { autoParallel: true, conflict: null };
+  }
+  for (const existing of sameLane) {
+    const existingPaths = Array.isArray(existing.claimedPaths) ? existing.claimedPaths : [];
+    if (existingPaths.length === 0) {
+      return { autoParallel: false, conflict: null };
+    }
+    const overlap = newPaths.filter((p) => existingPaths.includes(p));
+    if (overlap.length > 0) {
+      return {
+        autoParallel: false,
+        conflict: {
+          existingSpanId: existing.spanId || "unknown",
+          newSpanId: stamped.spanId || "unknown",
+          pair: { stage: stamped.stage, agent: stamped.agent },
+          conflictingPaths: overlap
+        }
+      };
+    }
+  }
+  return { autoParallel: true, conflict: null };
+}
+
+const MAX_PARALLEL_SLICE_IMPLEMENTERS_INLINE = 5;
+
+function readMaxParallelOverrideFromEnvInline() {
+  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;
+}
+
+// keep in sync with validateFanOutCap in src/delegation.ts
+function validateFanOutCapInline(stamped, activeEntries, override) {
+  if (stamped.agent !== "slice-implementer" || stamped.stage !== "tdd") return null;
+  if (stamped.status !== "scheduled") return null;
+  let cap;
+  if (override !== null && override !== undefined && Number.isInteger(override) && override >= 1) {
+    cap = override;
+  } else {
+    cap = readMaxParallelOverrideFromEnvInline() || MAX_PARALLEL_SLICE_IMPLEMENTERS_INLINE;
+  }
+  const sameLaneActive = activeEntries.filter(
+    (entry) =>
+      entry.stage === stamped.stage &&
+      entry.agent === stamped.agent &&
+      entry.spanId !== stamped.spanId
+  );
+  if (sameLaneActive.length + 1 > cap) {
+    return {
+      cap,
+      active: sameLaneActive.length,
+      pair: { stage: stamped.stage, agent: stamped.agent }
+    };
+  }
+  return null;
+}
+
 function enforceDispatchDedupInline(stamped, priorEntries, args) {
   if (stamped.status !== "scheduled") return null;
   if (args["allow-parallel"] === true) return null;
@@ -992,6 +1100,31 @@ async function main() {
     emitErrorJson("delegation_timestamp_non_monotonic", violation, json);
     return;
   }
+
+  // v6.10.0 (P1+P2): file-overlap scheduler + fan-out cap. Run before
+  // the legacy dispatch dedup so disjoint claimedPaths can auto-promote
+  // to allowParallel and bypass the duplicate guard.
+  if (status === "scheduled") {
+    const sameRunPrior = priorLedger.filter((entry) => entry.runId === runId);
+    const activeForRun = computeActiveSubagentsInline(sameRunPrior);
+    const overlap = validateFileOverlapInline(clean, activeForRun);
+    if (overlap.conflict) {
+      emitErrorJson("dispatch_overlap", overlap.conflict, json);
+      return;
+    }
+    if (overlap.autoParallel && clean.allowParallel !== true) {
+      clean.allowParallel = true;
+      args["allow-parallel"] = true;
+      event.allowParallel = true;
+    }
+    const overrideRaw = typeof args["override-cap"] === "string" ? args["override-cap"] : null;
+    const override = overrideRaw !== null ? Number(overrideRaw) : null;
+    const capViolation = validateFanOutCapInline(clean, activeForRun, override);
+    if (capViolation) {
+      emitErrorJson("dispatch_cap", capViolation, json);
+      return;
+    }
+  }
   const dedupViolation = enforceDispatchDedupInline(clean, priorLedger, args);
   if (dedupViolation) {
     if (dedupViolation.kind === "supersede") {

package/dist/content/reference-patterns.js

@@ -36,7 +36,7 @@ export const REFERENCE_PATTERNS = [
                     "Discover tests and affected contracts before opening a RED vertical slice.",
                     "Map the slice to the active source item before editing production code."
                 ],
-                artifactSections: ["Test Discovery", "System-Wide Impact Check", "Acceptance Mapping"]
+                artifactSections: ["Test Discovery", "System-Wide Impact Check", "Acceptance & Failure Map"]
             },
             {
                 stage: "review",
@@ -143,7 +143,7 @@ export const REFERENCE_PATTERNS = [
                     "Open one packet as one vertical slice; do not mix unrelated packet evidence.",
                     "Close packet only when RED, GREEN, REFACTOR, and verification evidence align."
                 ],
-                artifactSections: ["Acceptance Mapping", "RED Evidence", "GREEN Evidence", "REFACTOR Notes"]
+                artifactSections: ["Acceptance & Failure Map", "RED Evidence", "GREEN Evidence", "REFACTOR Notes"]
             }
         ]
     },

package/dist/content/skills.js

@@ -102,7 +102,7 @@ Any "the failure is real" claim (failing test, broken build, regression catch, d
 
 \`proof: <iso-ts> | <observed snippet — first 200 chars> | source: <command or log path>\`
 
-For TDD specifically, this is the watched-RED proof and is required per new test before \`stage-complete\` accepts the stage.
+For TDD specifically, this is the watched-RED proof and is required per new test before \`stage-complete\` accepts the stage. From v6.10.0 onward, record TDD slice transitions through the sidecar CLI \`cclaw-cli internal tdd-slice-record --slice <id> --status red|green|refactor-done|refactor-deferred ...\` rather than hand-editing the \`Watched-RED Proof\` or \`Vertical Slice Cycle\` markdown tables; the linter reads \`.cclaw/artifacts/06-tdd-slices.jsonl\` when present and treats the markdown as an auto-derived view.
 `;
 }
 /**

package/dist/content/stages/tdd.js

@@ -42,14 +42,14 @@ export const TDD = {
             "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.",
-            "Set execution posture — record whether this slice is sequential, batch-safe, or blocked; when the existing git workflow permits small commits, checkpoint after RED, GREEN, and REFACTOR (or record why commits are deferred).",
             "Use the mandatory `test-author` delegation for RED — after discovery and impact check, produce failing behavior tests and RED evidence only (no production edits). Set `CCLAW_ACTIVE_AGENT=tdd-red` when the harness supports phase labels.",
-            "RED: Capture failure output — copy the exact failure output as RED evidence. Record in artifact.",
+            "RED: Capture failure output — copy the exact failure output as RED evidence. Record the slice in `.cclaw/artifacts/06-tdd-slices.jsonl` via `cclaw-cli internal tdd-slice-record --slice <id> --status red --test-file <path> --command <cmd> --paths <comma-separated>` (the markdown `Watched-RED Proof` table is now auto-derived from this sidecar).",
             "Continue the same `test-author` delegation intent for GREEN — minimal implementation plus full-suite GREEN evidence. 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: continue the `test-author` evidence cycle (or a dedicated refactor mode when available) to improve code quality without behavior changes. Set `CCLAW_ACTIVE_AGENT=tdd-refactor` when the harness supports phase labels.",
+            "GREEN: append a `green` row to `.cclaw/artifacts/06-tdd-slices.jsonl` via `cclaw-cli internal tdd-slice-record --slice <id> --status green [--green-output-ref <path|spanId:...>]` so the Vertical Slice Cycle linter validates the sidecar instead of a hand-edited table.",
+            "REFACTOR: continue the `test-author` evidence cycle (or a dedicated refactor mode when available) to improve code quality without behavior changes, then record `--status refactor-done` (or `--status refactor-deferred --refactor-rationale \"<why>\"`) via the same `tdd-slice-record` CLI. Set `CCLAW_ACTIVE_AGENT=tdd-refactor` when the harness supports phase labels.",
             "Record evidence — capture test discovery, system-wide impact check, RED failure, GREEN output, and REFACTOR notes in the TDD artifact. 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.",
@@ -158,10 +158,8 @@ export const TDD = {
             { section: "Upstream Handoff", required: false, validationRule: "Summarizes plan/spec/design decisions, constraints, open questions, and explicit drift before RED work." },
             { section: "Test Discovery", required: true, validationRule: "Before RED: lists existing tests, fixtures/helpers, exact commands, and the chosen local pattern to extend." },
             { section: "System-Wide Impact Check", required: true, validationRule: "Before implementation: names affected callbacks, state transitions, interfaces, schemas, public APIs/config/CLI, persistence, or event contracts, with coverage or explicit out-of-scope notes." },
-            { section: "Execution Posture", required: false, validationRule: "Records sequential/batch/blocked posture and vertical-slice RED/GREEN/REFACTOR checkpoint plan, including incremental commit boundaries when consistent with the repository git workflow." },
             { section: "RED Evidence", required: true, validationRule: "Failing test output captured per slice." },
-            { section: "Acceptance Mapping", required: false, validationRule: "Each RED test links to a plan task and spec criterion." },
-            { section: "Failure Analysis", required: false, validationRule: "Failure reason matches expected missing behavior." },
+            { section: "Acceptance & Failure Map", required: false, validationRule: "Each slice row carries Source ID, AC ID, expected behavior, and a RED-link (delegation spanId, evidence path, or sidecar redOutputRef)." },
             { section: "GREEN Evidence", required: true, validationRule: "Full suite pass output captured." },
             { section: "REFACTOR Notes", required: true, validationRule: "What changed, why, behavior preservation confirmed." },
             { section: "Traceability", required: true, validationRule: "Plan task ID and spec criterion linked." },
@@ -302,11 +300,11 @@ function tddStageVariantForTrack(track) {
                 traceabilityRule: "Every RED test traces to an acceptance criterion. Every GREEN change traces to a RED test. Evidence chain must be unbroken."
             },
             artifactValidation: TDD.artifactRules.artifactValidation.map((row) => {
-                if (row.section === "Acceptance Mapping") {
+                if (row.section === "Acceptance & Failure Map") {
                     return {
                         ...row,
                         required: true,
-                        validationRule: "Each RED test links to a spec acceptance criterion ID (for example AC-1)."
+                        validationRule: "Each slice row carries Source ID, AC ID (spec acceptance criterion ID, for example AC-1), expected behavior, and a RED-link (delegation spanId, evidence path, or sidecar redOutputRef)."
                     };
                 }
                 if (row.section === "Traceability") {

package/dist/content/subagents.js

@@ -678,7 +678,7 @@ You are a slice-implementer subagent.
 
 SLICE: {single vertical slice}
 RED_EVIDENCE: {failing test and expected failure}
-ALLOWED_FILES: {explicit file boundaries}
+ALLOWED_FILES: {explicit file boundaries — surfaced to scheduler as Files: <paths>}
 FORBIDDEN_CHANGES: {scope/compatibility limits}
 VERIFICATION: {commands expected}
 
@@ -686,6 +686,12 @@ Rules:
 - Implement only the minimal GREEN change for the existing RED evidence.
 - Keep REFACTOR behavior-preserving.
 - Return the strict worker JSON schema first.
+
+Slice ledger contract (v6.10.0):
+- After observing the failing test, run \`cclaw-cli internal tdd-slice-record --slice <id> --status red --test-file <path> --command <cmd> --paths <comma-separated> [--ac <id>] [--plan-unit <id>]\`. The command appends to \`.cclaw/artifacts/06-tdd-slices.jsonl\`.
+- After the same test passes, run \`cclaw-cli internal tdd-slice-record --slice <id> --status green [--green-output-ref <path|spanId:...>]\`.
+- After REFACTOR, run \`cclaw-cli internal tdd-slice-record --slice <id> --status refactor-done\` or \`--status refactor-deferred --refactor-rationale "<why>"\`.
+- Do NOT hand-edit the Watched-RED Proof or Vertical Slice Cycle markdown tables; the linter reads the JSONL sidecar when present and the markdown becomes an auto-derived view.
 ${MARKDOWN_CODE_FENCE}
 
 `;
@@ -931,10 +937,12 @@ Process (mandatory):
 1) If STAGE_MODE=TEST_RED_ONLY:
    - RED only — add failing tests proving the gap (show failing output excerpt).
    - Do NOT edit production code.
+   - Append the slice to the sidecar via \`cclaw-cli internal tdd-slice-record --slice <id> --status red --test-file <path> --command <cmd> --paths <comma-separated>\` instead of editing the Watched-RED Proof markdown table.
    - Report: TESTS_ADDED, RED_COMMAND_RUN, RED_EVIDENCE, STATUS: DONE|BLOCKED.
 2) If STAGE_MODE=BUILD_GREEN_REFACTOR:
    - GREEN — minimal production code to satisfy existing RED tests, rerun full suite.
    - REFACTOR — only after full suite is green; preserve behavior.
+   - Append \`--status green\` (and \`--status refactor-done\` or \`--status refactor-deferred --refactor-rationale "<why>"\` after refactor) via \`cclaw-cli internal tdd-slice-record\`. The Vertical Slice Cycle markdown stays auto-derived from this sidecar.
    - Report: FILES_EDITED, GREEN_COMMAND_RUN, REFACTOR_NOTES, STATUS: DONE|BLOCKED.
 ${MARKDOWN_CODE_FENCE}
 

package/dist/content/templates.js

@@ -986,27 +986,17 @@ ${renderBehaviorAnchorTemplateLine("tdd")}
 |---|---|---|
 | 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 |  |  |  |
 
-## 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, an \`<artifacts-dir>/<file>\` evidence pointer, or a \`redOutputRef\` recorded via \`cclaw-cli internal tdd-slice-record\` in the sidecar ledger.
 
 ## GREEN Evidence
 - Full suite command:

package/dist/delegation.d.ts

@@ -129,6 +129,17 @@ 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[];
 };
 export declare const DELEGATION_LEDGER_SCHEMA_VERSION: 3;
 export type DelegationLedger = {
@@ -231,6 +242,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

@@ -224,7 +224,9 @@ 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"))));
 }
 function isDelegationDispatchSurface(value) {
     return typeof value === "string" && DELEGATION_DISPATCH_SURFACES.includes(value);
@@ -547,6 +549,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 +791,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));