cclaw-cli 6.11.0 → 6.13.0

package/dist/content/examples.js

@@ -36,10 +36,10 @@ export const BEHAVIOR_ANCHORS = [
     },
     {
         stage: "tdd",
-        section: "Watched-RED Proof",
-        bad: "Hand-edit Watched-RED Proof rows directly in the TDD artifact; the next lint overwrites the auto-rendered region and the slice still lacks a provable RED in delegation events.",
-        good: "Dispatch `test-author --slice S-1 --phase red`, then `slice-implementer --slice S-1 --phase green`. The linter auto-renders the slice cycle from `delegation-events.jsonl`.",
-        ruleHint: "RED/GREEN/REFACTOR transitions are recorded as `delegation-events.jsonl` rows via slice-tagged dispatches; the markdown tables are auto-rendered between `auto-start: tdd-slice-summary` markers from v6.11.0 onward."
+        section: "Vertical Slice Cycle",
+        bad: "Controller writes the failing test, the GREEN fix, AND per-slice prose into `06-tdd.md` itself, then hand-edits Watched-RED / Vertical Slice Cycle tables. `phase=red`/`green`/`doc` events missing; `tdd_slice_implementer_missing` and `tdd_slice_documenter_missing` block the gate.",
+        good: "Per slice: (1) `Task(\"test-author --slice S-1 --phase red\")`. Verify the event. (2) ONE message, TWO Tasks — `slice-implementer --phase green` AND `slice-documenter --phase doc`. (3) `slice-implementer --phase refactor` (or `refactor-deferred`). Linter auto-renders Vertical Slice Cycle from events.",
+        ruleHint: "Per-Slice Ritual (v6.12.0+): RED → verify → GREEN+DOC fan-out (one message, two Tasks) → REFACTOR. Controller never writes GREEN code or per-slice prose. Mandatory regardless of `discoveryMode`."
     },
     {
         stage: "review",

package/dist/content/hooks.js

@@ -350,6 +350,11 @@ function usage() {
     "  --slice=<id>              TDD slice identifier (e.g. S-1) used by the linter to auto-derive the Watched-RED + Vertical Slice Cycle tables.",
     "  --phase=<phase>           one of " + VALID_DELEGATION_PHASES.join(", ") + ". Pair with --slice to record a TDD slice phase event.",
     "  --refactor-rationale=<t>  required when --phase=refactor-deferred unless --evidence-ref carries the rationale text.",
+    "  --claim-token=<opaque>    v6.13 — required for worktree-first slice-implementer schedules with --slice (echo on all terminal rows for the span).",
+    "  --lane-id=<id>            v6.13 — worktree lane id (ownerLaneId metadata).",
+    "  --lease-until=<iso>       v6.13 — ISO8601 lease expiry for reclaim tooling.",
+    "  --depends-on=<a,b>       v6.13 — comma-separated plan unit ids for scheduler diagnostics.",
+    "  --integration-state=<s>  v6.13 — one of pending|applied|conflict|resolved|abandoned.",
     ""
   ].join("\\n") + "\\n");
 }
@@ -484,6 +489,42 @@ function buildRow(args, status, runId, now, options) {
       resolvedEvidenceRefs = [rationale, ...resolvedEvidenceRefs];
     }
   }
+  const integrationStateRaw =
+    typeof args["integration-state"] === "string" ? args["integration-state"].trim() : "";
+  const integrationStateAllowed = new Set([
+    "pending",
+    "applied",
+    "conflict",
+    "resolved",
+    "abandoned"
+  ]);
+  const integrationState =
+    integrationStateRaw.length > 0 && integrationStateAllowed.has(integrationStateRaw)
+      ? integrationStateRaw
+      : undefined;
+  const claimToken =
+    typeof args["claim-token"] === "string" && args["claim-token"].trim().length > 0
+      ? args["claim-token"].trim()
+      : undefined;
+  const ownerLaneId =
+    typeof args["lane-id"] === "string" && args["lane-id"].trim().length > 0
+      ? args["lane-id"].trim()
+      : undefined;
+  const leasedUntil =
+    typeof args["lease-until"] === "string" && args["lease-until"].trim().length > 0
+      ? args["lease-until"].trim()
+      : undefined;
+  const dependsOnRaw =
+    typeof args["depends-on"] === "string" ? args["depends-on"].trim() : "";
+  const dependsOn =
+    dependsOnRaw.length > 0
+      ? dependsOnRaw
+        .split(",")
+        .map((value) => value.trim())
+        .filter((value) => value.length > 0)
+      : undefined;
+  const leaseState =
+    leasedUntil && status === "scheduled" ? "claimed" : undefined;
   return {
     stage: args.stage,
     agent: args.agent,
@@ -508,7 +549,13 @@ function buildRow(args, status, runId, now, options) {
     allowParallel: args["allow-parallel"] === true ? true : undefined,
     claimedPaths: claimedPaths.length > 0 ? claimedPaths : undefined,
     sliceId,
-    phase
+    phase,
+    claimToken,
+    ownerLaneId,
+    leasedUntil,
+    leaseState,
+    dependsOn,
+    integrationState
   };
 }
 

package/dist/content/skills.d.ts

@@ -18,6 +18,16 @@ export declare function watchedFailProofBlock(): string;
 export declare const INVESTIGATION_DISCIPLINE_STAGES: ReadonlySet<FlowStage>;
 export declare function investigationDisciplineBlock(): string;
 export declare function behaviorAnchorBlock(stage: FlowStage): string;
+/**
+ * v6.12.0 Phase Ritual + Phase W — TDD-only top-of-skill sections that
+ * sit immediately after the `<EXTREMELY-IMPORTANT>` Iron Law block and
+ * before `## Quick Start`. They establish the per-slice three-dispatch
+ * ritual + wave batch mode in imperative voice with literal commands so
+ * pattern-matching on read works in our favor.
+ *
+ * Empty for non-TDD stages.
+ */
+export declare function tddTopOfSkillBlock(stage: FlowStage): string;
 export declare function stageSkillFolder(stage: FlowStage): string;
 export declare function stageSkillMarkdown(stage: FlowStage, track?: FlowTrack): string;
 export declare function executingWavesSkillMarkdown(): string;

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. From v6.11.0 onward, the controller dispatches \`test-author --slice S-<id> --phase red\` (and later \`slice-implementer --phase green\`, \`--phase refactor\` or \`--phase refactor-deferred --refactor-rationale "<why>"\`) and the linter auto-derives the \`Watched-RED Proof\` and \`Vertical Slice Cycle\` tables in \`06-tdd.md\` from \`.cclaw/state/delegation-events.jsonl\`. Do NOT hand-edit those tables. v6.10.0 sidecar (\`06-tdd-slices.jsonl\`) is removed; \`cclaw-cli sync\` cleans the file from existing installs.
+For TDD specifically, this is the watched-RED proof and is required per new test before \`stage-complete\` accepts the stage. From v6.12.0 onward, every slice on every TDD run dispatches three roles in this exact order: (1) \`test-author --slice S-<id> --phase red\`, (2) ONE message with TWO concurrent Task calls — \`slice-implementer --slice S-<id> --phase green --paths <production paths>\` AND \`slice-documenter --slice S-<id> --phase doc --paths <artifacts-dir>/tdd-slices/S-<id>.md\`, (3) \`slice-implementer --phase refactor\` or \`--phase refactor-deferred --refactor-rationale "<why>"\`. The linter auto-derives the \`Watched-RED Proof\` and \`Vertical Slice Cycle\` tables in \`06-tdd.md\` from \`.cclaw/state/delegation-events.jsonl\`. Do NOT hand-edit those tables. \`slice-implementer\` and \`slice-documenter\` are mandatory regardless of \`discoveryMode\` (v6.12.0 Phase R/M); the controller MUST NOT write GREEN production code or per-slice prose itself. v6.10.0 sidecar (\`06-tdd-slices.jsonl\`) is removed; \`cclaw-cli sync\` cleans the file from existing installs.
 `;
 }
 /**
@@ -168,6 +168,68 @@ function whenNotToUseBlock(items) {
     return `## When Not to Use
 ${items.map((item) => `- ${item}`).join("\n")}
 
+`;
+}
+/**
+ * v6.12.0 Phase Ritual + Phase W — TDD-only top-of-skill sections that
+ * sit immediately after the `<EXTREMELY-IMPORTANT>` Iron Law block and
+ * before `## Quick Start`. They establish the per-slice three-dispatch
+ * ritual + wave batch mode in imperative voice with literal commands so
+ * pattern-matching on read works in our favor.
+ *
+ * Empty for non-TDD stages.
+ */
+export function tddTopOfSkillBlock(stage) {
+    if (stage !== "tdd")
+        return "";
+    return `## Per-Slice Ritual (v6.12.0+)
+
+ONE slice = THREE dispatches, in this order. Do not skip, do not collapse.
+
+1. **RED** — \`Task("test-author --slice S-<id> --phase red")\`.
+2. **Verify RED** — wait for the \`phase=red\` event in \`.cclaw/state/delegation-events.jsonl\` with non-empty \`evidenceRefs\`. No production edits.
+3. **GREEN+DOC fan-out** — ONE message, TWO concurrent Tasks:
+   \`\`\`
+   Task("slice-implementer --slice S-<id> --phase green --paths <prod paths>")
+   Task("slice-documenter  --slice S-<id> --phase doc   --paths <artifacts-dir>/tdd-slices/S-<id>.md")
+   \`\`\`
+   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>'\`.
+
+**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\`.
+
+## Wave Batch Mode (v6.12.0+)
+
+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\`.
+
+**Phase A — RED checkpoint** — ONE message, all test-authors:
+\`\`\`
+Task("test-author --slice S-1 --phase red")
+Task("test-author --slice S-2 --phase red")
+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:
+\`\`\`
+Task("slice-implementer --slice S-1 --phase green --paths <S-1 prod>")
+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).
+
+**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.
+
+**slice-documenter** may mark prose \`provisional\` until GREEN is proven; finalize \`tdd-slices/S-<id>.md\` after GREEN evidence is recorded.
+
 `;
 }
 function artifactTemplatePathForStage(stage) {
@@ -593,7 +655,7 @@ If you are about to violate the Iron Law, STOP. No amount of urgency, partial pr
 
 </EXTREMELY-IMPORTANT>
 
-${quickStartBlock(stage, track)}
+${tddTopOfSkillBlock(stage)}${quickStartBlock(stage, track)}
 
 ${STAGE_LANGUAGE_POLICY_POINTER}
 ## Philosophy

package/dist/content/stage-schema.js

@@ -117,6 +117,7 @@ function defaultReturnSchemaForAgent(agent) {
         case "feasibility-reviewer":
             return "review-return";
         case "slice-implementer":
+        case "slice-documenter":
             return "worker-return";
         case "release-reviewer":
             return "release-return";
@@ -143,7 +144,7 @@ function defaultReturnSchemaForAgent(agent) {
 function dispatchClassForRow(row) {
     if (row.dispatchClass)
         return row.dispatchClass;
-    if (row.agent === "fixer" || row.agent === "slice-implementer")
+    if (row.agent === "fixer" || row.agent === "slice-implementer" || row.agent === "slice-documenter")
         return "worker";
     return row.skill?.includes("review") || row.agent === "reviewer" || row.agent === "security-reviewer" || row.agent.endsWith("-reviewer")
         ? "review-lens"
@@ -721,10 +722,18 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
         },
         {
             agent: "slice-implementer",
-            mode: "proactive",
+            mode: "mandatory",
+            requiredAtTier: "lightweight",
+            when: "Always for GREEN and REFACTOR phases. Controller MUST NOT write production code itself.",
+            purpose: "Implement the minimal passing slice inside explicit file boundaries and return strict worker evidence. v6.12.0 Phase M makes this dispatch mandatory; the linter rule `tdd_slice_implementer_missing` blocks the gate when GREEN was authored by anyone other than `slice-implementer`.",
+            requiresUserGate: false
+        },
+        {
+            agent: "slice-documenter",
+            mode: "mandatory",
             requiredAtTier: "lightweight",
-            when: "When a bounded GREEN/REFACTOR slice has non-overlapping file ownership and a clear RED failure.",
-            purpose: "Implement the minimal passing slice inside explicit file boundaries and return strict worker evidence.",
+            when: "Always in PARALLEL with `slice-implementer --phase green` for the same slice.",
+            purpose: "Write per-slice prose into `<artifacts-dir>/tdd-slices/S-<id>.md` while production code is being implemented. v6.12.0 Phase R makes this mandatory regardless of `discoveryMode`; the linter rule `tdd_slice_documenter_missing` blocks the gate when a `phase=doc` event is missing.",
             requiresUserGate: false
         },
         {

package/dist/content/stages/plan.js

@@ -46,6 +46,7 @@ export const PLAN = {
             "Slice into vertical tasks — each task targets 2-5 minutes, produces one testable outcome, and touches one coherent area.",
             "Task Contract — every task has one coherent outcome, AC mapping, exact verification command/manual step, and expected evidence snippet or pass condition. Avoid vague `run tests` wording.",
             "Annotate slice-review metadata — task rows may carry `touchCount` (rough number of files expected to change), `touchPaths` (glob hints, e.g. `migrations/**`, `src/auth/**`), and optional `highRisk: true` to force a review pass. These fields feed the TDD stage's Per-Slice Review point.",
+            "For every `### Implementation Unit U-<n>`, declare v6.13.0 parallel metadata bullets: `id`, `dependsOn` (unit ids or `none`), `claimedPaths` (repo-relative), `parallelizable` (true|false), `riskTier` (low|standard|high), optional `lane` — used for conflict-aware wave plans and schedulers.",
             "Map scope Locked Decisions — every D-XX ID from scope is referenced by at least one plan task (or explicitly marked deferred with reason).",
             "Run anti-placeholder + anti-scope-reduction scans — block `TODO/TBD/...` and phrasing like `v1`, `for now`, `later` for locked boundaries.",
             "Define validation points — mark where progress must be checked before continuing, with concrete command and expected evidence.",
@@ -135,7 +136,7 @@ export const PLAN = {
             { section: "Locked Decision Coverage", required: false, validationRule: "Every locked decision ID (D-XX) from scope is listed with linked task IDs or explicit defer rationale." },
             { section: "Risk Assessment", required: false, validationRule: "If present: per-task or per-batch risk identification with likelihood, impact, and mitigation strategy." },
             { section: "Boundary Map", required: false, validationRule: "If present: per-batch or per-task interface contracts listing what each task produces (exports) and consumes (imports) from other tasks." },
-            { section: "Implementation Units", required: false, validationRule: "If present: each `### Implementation Unit U-<n>` includes Goal, Files, Approach, Test scenarios, and Verification fields." },
+            { section: "Implementation Units", required: false, validationRule: "If present: each `### Implementation Unit U-<n>` includes Goal, Files, Approach, Test scenarios, Verification fields, plus v6.13.0 bullets (`id`, `dependsOn`, `claimedPaths`, `parallelizable`, `riskTier`, optional `lane`)." },
             { section: "Calibrated Findings", required: false, validationRule: "If present: either `None this stage` or one or more lines in `[P1|P2|P3] (confidence: <n>/10) <path>[:<line>] — <description>` format." },
             { section: "Regression Iron Rule", required: false, validationRule: "If present: includes `Iron rule acknowledged: yes`." },
             { section: "WAIT_FOR_CONFIRM", required: true, validationRule: "Explicit marker present. Status: pending until user approves." },

package/dist/content/stages/schema-types.d.ts

@@ -20,7 +20,7 @@ export interface ArtifactValidation {
     tier?: "required" | "recommended";
     validationRule: string;
 }
-export type StageSubagentName = "researcher" | "architect" | "spec-validator" | "spec-document-reviewer" | "coherence-reviewer" | "scope-guardian-reviewer" | "feasibility-reviewer" | "slice-implementer" | "release-reviewer" | "planner" | "product-discovery" | "divergent-thinker" | "critic" | "reviewer" | "security-reviewer" | "integration-overseer" | "test-author" | "doc-updater" | "fixer";
+export type StageSubagentName = "researcher" | "architect" | "spec-validator" | "spec-document-reviewer" | "coherence-reviewer" | "scope-guardian-reviewer" | "feasibility-reviewer" | "slice-implementer" | "slice-documenter" | "release-reviewer" | "planner" | "product-discovery" | "divergent-thinker" | "critic" | "reviewer" | "security-reviewer" | "integration-overseer" | "test-author" | "doc-updater" | "fixer";
 export type StageSubagentDispatchClass = "stage-specialist" | "worker" | "review-lens";
 export type StageSubagentReturnSchema = "planning-return" | "product-return" | "critic-return" | "review-return" | "security-return" | "tdd-return" | "docs-return" | "worker-return" | "fixer-return" | "research-return" | "architecture-return" | "spec-validation-return" | "release-return";
 export interface StageAutoSubagentDispatch {

package/dist/content/stages/spec.js

@@ -62,7 +62,7 @@ export const SPEC = {
             "Define measurable acceptance criteria.",
             "Capture constraints, assumptions, and edge cases.",
             "Review assumptions before finalization: source/confidence, validation path, and accepted/rejected/open disposition.",
-            "Build Acceptance Mapping: AC -> design decision -> observable evidence -> verification method -> likely test level.",
+            "Annotate parallel-slice metadata on each acceptance criterion: `parallelSafe` (true|false) and `touchSurface` (repo-relative paths/modules expected to change) so downstream plan units and TDD lanes stay conflict-aware (v6.13.0).",
             "Confirm every verification method is concrete enough for plan/TDD to use later.",
             "Present acceptance criteria to the user in 3-5-item batches, pausing for explicit ACK between batches (see Interaction Protocol).",
             "Write spec artifact and request approval."
@@ -118,7 +118,7 @@ export const SPEC = {
         },
         artifactValidation: [
             { section: "Upstream Handoff", required: false, validationRule: "Summarizes scope/design decisions, constraints, open questions, and explicit drift before acceptance criteria." },
-            { section: "Acceptance Criteria", required: true, validationRule: "Each criterion is observable, measurable, and falsifiable. Standard track should include Requirement Ref and Design Decision Ref columns; quick track may instead link each AC to the reproduction contract or bug slice. AC IDs (AC-1, AC-2…) are stable across revisions — dropped ACs stay with Priority `DROPPED`." },
+            { section: "Acceptance Criteria", required: true, validationRule: "Each criterion is observable, measurable, and falsifiable. Standard track should include Requirement Ref and Design Decision Ref columns; quick track may instead link each AC to the reproduction contract or bug slice. AC IDs (AC-1, AC-2…) are stable across revisions — dropped ACs stay with Priority `DROPPED`. v6.13.0: each AC declares `parallelSafe` (true|false) and `touchSurface` (paths/modules) for parallel slice planning." },
             { section: "Quick Reproduction Contract", required: false, validationRule: "Quick bug-fix specs own the reproduction contract: symptom, repro steps, expected RED test behavior, and acceptance criterion." },
             { section: "Edge Cases", required: true, validationRule: "At least one boundary and one error condition per criterion." },
             { section: "Constraints and Assumptions", required: false, validationRule: "Constraints are CARRIED FORWARD from scope's `## Scope Contract > Constraints` (cite with `See scope: <ref>` or copy with attribution). New spec-stage constraints (rare) get a citation to the spec-stage Q&A row that surfaced them. Assumptions are owned by `## Assumptions Before Finalization` — do NOT duplicate them here. Section may be `- See scope: 02-scope.md#constraints.` for the common case." },

package/dist/content/stages/tdd.js

@@ -49,8 +49,9 @@ export const TDD = {
             "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): when `discoveryMode === \"deep\"` is active, dispatch `slice-documenter --slice S-<id> --phase doc` IN PARALLEL with `slice-implementer` for the same slice. The documenter only writes `<artifacts-dir>/tdd-slices/S-<id>.md`, so its `--paths` are disjoint from the implementer's production code and the file-overlap scheduler auto-allows the parallel dispatch.",
-            "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.",
+            "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.",
+            "**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).",
@@ -62,7 +63,7 @@ export const TDD = {
             "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.",
-            "Slice-documenter (Phase C, opt-in / mandatory on discoveryMode=deep): in parallel with `slice-implementer --phase green`, dispatch `slice-documenter --slice S-<id> --phase doc` whose only `claimedPaths` is `<artifacts-dir>/tdd-slices/S-<id>.md`. The two dispatches run concurrently because their paths are disjoint. The documenter writes per-slice prose so the main `06-tdd.md` stays thin.",
+            "Slice-documenter (mandatory v6.12.0, regardless of `discoveryMode`): in PARALLEL with `slice-implementer --phase green`, dispatch `slice-documenter --slice S-<id> --phase doc` whose only `claimedPaths` is `<artifacts-dir>/tdd-slices/S-<id>.md`. The two dispatches run concurrently because their paths are disjoint. The documenter writes per-slice prose so the main `06-tdd.md` stays thin. Controller MUST NOT author per-slice prose; controller MUST NOT author GREEN production code (use `slice-implementer`).",
             "Run source/test preflight using configured TDD path patterns where feasible; if path classification is impossible (generated files, non-file side effect), record why.",
             "Write behavior-focused tests before changing implementation (RED).",
             "Capture and store failing output as RED evidence.",
@@ -109,16 +110,16 @@ export const TDD = {
             "Relevant existing test files, helpers, fixtures, and exact commands identified before RED.",
             "Callbacks, state transitions, interfaces, schemas, and contracts checked for impact before implementation.",
             "Execution posture and vertical-slice RED/GREEN/REFACTOR checkpoint plan recorded, including commit boundaries when the repo workflow supports them.",
-            "RED observability: a `phase=red` event in `delegation-events.jsonl` for each slice with non-empty evidenceRefs (test path, span ref, or pasted-output pointer). Legacy `## Watched-RED Proof` / `## RED Evidence` markdown tables remain valid as a fallback.",
-            "GREEN observability: a `phase=green` event in `delegation-events.jsonl` per slice whose `completedTs` >= the matching `phase=red` `completedTs` and whose evidenceRefs name the failing-now-passing test. Legacy `## GREEN Evidence` block remains valid as a fallback.",
+            "RED observability: a `phase=red` event in `delegation-events.jsonl` for each slice with non-empty evidenceRefs (test path, span ref, or pasted-output pointer). Slices created **before the v6.12.0 cutover marker** in `flow-state.json::tddCutoverSliceId` may retain legacy `## Watched-RED Proof` / `## RED Evidence` markdown tables; slices created **after the cutover marker** MUST use phase events + slice-documenter doc, and legacy table writes are surfaced by the advisory `tdd_legacy_section_writes_after_cutover` rule.",
+            "GREEN observability: a `phase=green` event in `delegation-events.jsonl` per slice whose `completedTs` >= the matching `phase=red` `completedTs`, authored by `slice-implementer` (linter rule `tdd_slice_implementer_missing` blocks the gate otherwise), and whose evidenceRefs name the failing-now-passing test. Pre-cutover slices may keep legacy `## GREEN Evidence` markdown.",
             "REFACTOR observability: per slice, a `phase=refactor` event OR a `phase=refactor-deferred` event whose evidenceRefs / refactor rationale captures why refactor was deferred.",
+            "Per slice, a `phase=doc` event from `slice-documenter` whose evidenceRefs name `<artifacts-dir>/tdd-slices/S-<id>.md`. Mandatory regardless of `discoveryMode` (v6.12.0 Phase R). Linter rule `tdd_slice_documenter_missing` blocks the gate when missing.",
             "Fresh verification evidence recorded with command, PASS/FAIL status, and commit SHA or no-VCS reason plus content/artifact hash before completion.",
             "Iron Law Acknowledgement section explicitly states `Acknowledged: yes`.",
             "Acceptance mapping documented.",
             "Failure reason analysis recorded.",
             "Refactor rationale captured.",
-            "Traceability to task identifier is documented.",
-            "On discoveryMode=deep: per slice, a `phase=doc` event from `slice-documenter` whose evidenceRefs name `<artifacts-dir>/tdd-slices/S-<id>.md`. On other discovery modes the documenter event is advisory."
+            "Traceability to task identifier is documented."
         ],
         inputs: ["approved plan slice", "spec acceptance criterion", "test harness configuration", "coding standards and constraints"],
         requiredContext: ["plan artifact", "spec artifact", "existing test patterns", "affected contracts and state boundaries"],

package/dist/content/templates.js

@@ -739,11 +739,11 @@ ${renderBehaviorAnchorTemplateLine("spec")}
 - Drift from upstream (or \`None\`):
 
 ## Acceptance Criteria
-| ID | Requirement Ref (R#) | Criterion (observable/measurable/falsifiable) | Design Decision Ref (D-XX) |
-|---|---|---|---|
-| AC-1 | R1 |  |  |
+| ID | Requirement Ref (R#) | Criterion (observable/measurable/falsifiable) | Design Decision Ref (D-XX) | parallelSafe (true/false) | touchSurface (paths/modules) |
+|---|---|---|---|---|---|
+| AC-1 | R1 |  |  | false |  |
 
-> Standard ACs reference at least one \`R#\` from \`02-scope.md\`. Quick-track ACs may instead put \`Quick Reproduction Contract\` / bug-slice refs in the Requirement Ref column and \`N/A\` for Design Decision Ref. ACs are stable (never renumber): dropped ACs stay with Priority \`DROPPED\`; new ones append with the next free \`AC-#\`.
+> Standard ACs reference at least one \`R#\` from \`02-scope.md\`. Quick-track ACs may instead put \`Quick Reproduction Contract\` / bug-slice refs in the Requirement Ref column and \`N/A\` for Design Decision Ref. ACs are stable (never renumber): dropped ACs stay with Priority \`DROPPED\`; new ones append with the next free \`AC-#\`. **v6.13.0:** \`parallelSafe\` states whether this AC can be proven in parallel with others; \`touchSurface\` lists repo-relative globs or modules this AC is expected to touch (scheduler + slice planning).
 
 ## Quick Reproduction Contract
 > Required for quick bug-fix specs; use \`N/A\` for non-bugfix or standard/medium tracks. TDD turns this contract into the RED reproduction test.
@@ -907,6 +907,12 @@ Execution rule: complete and verify each batch before starting the next batch.
 > Required structural form per implementation unit. Use ≥1 unit; bite-sized 2-5 minute steps inside each. The linter validates shape, not topic.
 
 ### Implementation Unit U-1
+- **id:** U-1
+- **dependsOn:** none
+- **claimedPaths:** (repo-relative, comma-separated globs or files this unit expects to own)
+- **parallelizable:** true
+- **riskTier:** standard
+- **lane:** (optional advisory lane tag for human-readable batching)
 - **Goal:**
 - **Requirements (from Spec):**
 - **Dependencies (other units):**

package/dist/delegation.d.ts

@@ -1,7 +1,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 FlowState } from "./flow-state.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"];
@@ -164,9 +164,26 @@ export type DelegationEntry = {
      * keep in sync with the inline copy in
      * `src/content/hooks.ts::delegationRecordScript`.
      */
-    phase?: "red" | "green" | "refactor" | "refactor-deferred" | "doc";
+    phase?: "red" | "green" | "refactor" | "refactor-deferred" | "doc" | "resolve-conflict";
+    /**
+     * v6.13.0 — opaque token tying scheduled work to terminal lifecycle rows
+     * under worktree-first execution (mandatory on new schedules).
+     */
+    claimToken?: string;
+    /** v6.13.0 — lane / worktree id owning the slice checkout. */
+    ownerLaneId?: string;
+    /** v6.13.0 — ISO lease expiry for reclaim sweeps. */
+    leasedUntil?: string;
+    /** v6.13.0 — lease bookkeeping for audit + reclaim tooling. */
+    leaseState?: "claimed" | "expired" | "released" | "reclaimed";
+    /** v6.13.0 — plan unit dependency ids echoed for scheduler diagnostics. */
+    dependsOn?: string[];
+    /**
+     * v6.13.0 — integration branch merge status after deterministic fan-in.
+     */
+    integrationState?: "pending" | "applied" | "conflict" | "resolved" | "abandoned";
 };
-export declare const DELEGATION_PHASES: readonly ["red", "green", "refactor", "refactor-deferred", "doc"];
+export declare const DELEGATION_PHASES: readonly ["red", "green", "refactor", "refactor-deferred", "doc", "resolve-conflict"];
 export type DelegationPhase = (typeof DELEGATION_PHASES)[number];
 export declare const DELEGATION_LEDGER_SCHEMA_VERSION: 3;
 export type DelegationLedger = {
@@ -191,9 +208,31 @@ export type DelegationEvent = DelegationEntry & {
  */
 export declare function isTrustBoundaryPath(filePath: string): boolean;
 export declare function readDelegationLedger(projectRoot: string): Promise<DelegationLedger>;
+/** Parsed `cclaw_fanin_*` audit rows from `delegation-events.jsonl`. */
+export interface FanInAuditRecord {
+    event: "cclaw_fanin_applied" | "cclaw_fanin_conflict" | "cclaw_fanin_resolved" | "cclaw_fanin_abandoned";
+    runId?: string;
+    laneId?: string;
+    sliceIds?: string[];
+    integrationBranch?: string;
+    details?: string;
+    ts: string;
+}
+/**
+ * Append a deterministic fan-in audit row (not a delegation lifecycle event).
+ */
+export declare function recordCclawFanInAudit(projectRoot: string, params: {
+    kind: FanInAuditRecord["event"];
+    runId: string;
+    laneId: string;
+    sliceIds: string[];
+    integrationBranch: string;
+    details?: string;
+}): Promise<void>;
 export declare function readDelegationEvents(projectRoot: string): Promise<{
     events: DelegationEvent[];
     corruptLines: number[];
+    fanInAudits: FanInAuditRecord[];
 }>;
 /**
  * Fold ledger entries to the latest row per `spanId` and keep only spans
@@ -319,12 +358,38 @@ export declare class DispatchCapError extends Error {
         };
     });
 }
+/**
+ * v6.13.0 — claim / lease contract violation for worktree-first TDD rows.
+ */
+export declare class DispatchClaimInvalidError extends Error {
+    constructor(message: 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;
+export interface ReadySliceUnit {
+    unitId: string;
+    sliceId: string;
+    dependsOn: string[];
+    claimedPaths: string[];
+    parallelizable: boolean;
+}
+export interface SelectReadySlicesOptions {
+    cap: number;
+    completedUnitIds: ReadonlySet<string>;
+    activePathHolders: ReadonlyArray<{
+        paths: string[];
+    }>;
+    legacyContinuation: boolean;
+}
+/**
+ * Return up to `cap` slice units whose dependsOn are satisfied, avoiding
+ * `claimedPaths` intersections with already-selected units and active holders.
+ */
+export declare function selectReadySlices(units: ReadySliceUnit[], opts: SelectReadySlicesOptions): ReadySliceUnit[];
 /**
  * v6.10.0 (P1) — when scheduling a `slice-implementer` on a TDD stage,
  * compare `claimedPaths` against every currently active span on the
@@ -369,6 +434,11 @@ export declare function validateFanOutCap(stamped: DelegationEntry, activeEntrie
  */
 export declare function findActiveSpanForPair(stage: string, agent: string, runId: string, ledger: DelegationLedger): DelegationEntry | null;
 export declare function appendDelegation(projectRoot: string, entry: DelegationEntry): Promise<void>;
+/**
+ * Scan delegation events for expired `leasedUntil` timestamps and append
+ * best-effort `cclaw_slice_lease_expired` audit rows (one per span/slice key).
+ */
+export declare function reclaimExpiredDelegationClaims(projectRoot: string, now?: Date): Promise<number>;
 /**
  * Aggregate the fulfillment mode cclaw expects for the active harness set.
  * Priority native > generic-dispatch > role-switch > waiver — the best