cclaw-cli 6.10.0 → 6.12.0

package/dist/artifact-linter.js

@@ -5,7 +5,6 @@ import { exists } from "./fs-utils.js";
 import { stageSchema } from "./content/stage-schema.js";
 import { readFlowState } from "./run-persistence.js";
 import { duplicateH2Headings, extractEvidencePointers, extractH2Sections, extractRequirementIdsFromMarkdown, isShortCircuitActivated, normalizeHeadingTitle, parseFrontmatter, parseLearningsSection, sectionBodyByAnyName, sectionBodyByHeadingPrefix, sectionBodyByName, validateSectionBody, formatLearningsErrorsBullets } from "./artifact-linter/shared.js";
-import { foldTddSliceLedger, readTddSliceLedger } from "./tdd-slices.js";
 import { shouldDemoteArtifactValidationByTrack } from "./content/stage-schema.js";
 import { readDelegationLedger, recordArtifactValidationDemotedByTrack } from "./delegation.js";
 import { classifyAndPersistFindings } from "./artifact-linter/findings-dedup.js";
@@ -147,11 +146,12 @@ export async function lintArtifact(projectRoot, stage, track = "standard", optio
         }
     }
     const liteTierForValidators = shouldDemoteArtifactValidationByTrack(track, taskClass);
-    // v6.10.0 (T3) — pre-resolve RED/GREEN Evidence pointers and sidecar
-    // auto-satisfy state once for the whole TDD loop, then thread the
-    // booleans through `validateSectionBody`. We do the async resolution
-    // here (path existence + delegation spanId match) so the validators
-    // themselves stay sync.
+    // v6.11.0 (D5) — pre-resolve RED/GREEN Evidence pointers AND
+    // delegation phase events so `validateSectionBody` (sync) can
+    // short-circuit. The Evidence: pointer mode (v6.10.0 T3) stays as a
+    // fallback alongside legacy markdown content; phase events with a
+    // `phase=red`/`phase=green` row plus non-empty evidenceRefs auto-pass
+    // the corresponding markdown validator.
     const tddEvidenceContext = stage === "tdd"
         ? await resolveTddEvidencePointerContext({
             projectRoot,
@@ -435,14 +435,21 @@ const ARTIFACT_VALIDATION_LITE_DEMOTE_SECTIONS = new Set([
     "Product Discovery Delegation (Strategist Mode)"
 ]);
 /**
- * v6.10.0 (T3) — pre-resolve `Evidence:` pointers and sidecar
- * auto-satisfy state for the TDD stage's RED/GREEN Evidence rows so
- * `validateSectionBody` (sync) can short-circuit. A pointer of the form
- * `<path>` is satisfied when the path exists on disk relative to the
- * project root; `spanId:<id>` is satisfied when any delegation ledger
- * row carries that span id. Sidecar auto-satisfy fires when
- * `06-tdd-slices.jsonl` carries at least one slice with a non-empty
- * `redOutputRef` / `greenOutputRef`.
+ * v6.11.0 (D5) — pre-resolve `Evidence:` pointers and delegation
+ * phase-event auto-satisfy state for the TDD stage's RED/GREEN
+ * Evidence rows so `validateSectionBody` (sync) can short-circuit.
+ *
+ * - `<path>` pointer is satisfied when the path exists on disk relative
+ *   to the project root.
+ * - `spanId:<id>` pointer is satisfied when any delegation ledger row
+ *   carries that span id.
+ * - Phase-event auto-satisfy fires when `delegation-events.jsonl`
+ *   carries at least one slice-tagged event for the active run with
+ *   `phase=red`/`phase=green` and non-empty `evidenceRefs`. This is the
+ *   v6.11.0 replacement for the v6.10.0 sidecar auto-satisfy hook —
+ *   slice events are now the source of truth, the RED/GREEN markdown
+ *   tables are auto-rendered from them, and the validators MUST NOT
+ *   demand pasted stdout when the events already prove RED/GREEN.
  */
 async function resolveTddEvidencePointerContext(input) {
     const { projectRoot, sections } = input;
@@ -451,16 +458,29 @@ async function resolveTddEvidencePointerContext(input) {
     const redPointers = extractEvidencePointers(redSection);
     const greenPointers = extractEvidencePointers(greenSection);
     let knownSpanIds = new Set();
-    if (redPointers.length > 0 || greenPointers.length > 0) {
-        try {
-            const ledger = await readDelegationLedger(projectRoot);
-            knownSpanIds = new Set(ledger.entries
-                .map((entry) => entry.spanId)
-                .filter((id) => typeof id === "string" && id.length > 0));
-        }
-        catch {
-            knownSpanIds = new Set();
-        }
+    let phaseEventsAutoSatisfy = { red: false, green: false };
+    try {
+        const ledger = await readDelegationLedger(projectRoot);
+        knownSpanIds = new Set(ledger.entries
+            .map((entry) => entry.spanId)
+            .filter((id) => typeof id === "string" && id.length > 0));
+        const runId = ledger.runId;
+        const slicePhaseRows = ledger.entries.filter((entry) => entry.runId === runId &&
+            entry.stage === "tdd" &&
+            typeof entry.sliceId === "string" &&
+            entry.sliceId.length > 0 &&
+            typeof entry.phase === "string");
+        const redOk = slicePhaseRows.some((entry) => entry.phase === "red" &&
+            Array.isArray(entry.evidenceRefs) &&
+            entry.evidenceRefs.some((ref) => typeof ref === "string" && ref.trim().length > 0));
+        const greenOk = slicePhaseRows.some((entry) => entry.phase === "green" &&
+            Array.isArray(entry.evidenceRefs) &&
+            entry.evidenceRefs.some((ref) => typeof ref === "string" && ref.trim().length > 0));
+        phaseEventsAutoSatisfy = { red: redOk, green: greenOk };
+    }
+    catch {
+        knownSpanIds = new Set();
+        phaseEventsAutoSatisfy = { red: false, green: false };
     }
     async function pointerResolves(value) {
         const trimmed = value.replace(/[`*_]/gu, "").trim();
@@ -480,28 +500,14 @@ async function resolveTddEvidencePointerContext(input) {
         }
         return false;
     }
-    let redSidecarAutoSatisfy = false;
-    let greenSidecarAutoSatisfy = false;
-    try {
-        const sidecar = await readTddSliceLedger(projectRoot);
-        if (sidecar.entries.length > 0) {
-            const folded = foldTddSliceLedger(sidecar.entries);
-            redSidecarAutoSatisfy = folded.some((entry) => typeof entry.redOutputRef === "string" && entry.redOutputRef.length > 0);
-            greenSidecarAutoSatisfy = folded.some((entry) => typeof entry.greenOutputRef === "string" && entry.greenOutputRef.length > 0);
-        }
-    }
-    catch {
-        redSidecarAutoSatisfy = false;
-        greenSidecarAutoSatisfy = false;
-    }
     return {
         red: {
             pointerSatisfied: await anyResolved(redPointers),
-            sidecarAutoSatisfy: redSidecarAutoSatisfy
+            phaseEventsSatisfied: phaseEventsAutoSatisfy.red
         },
         green: {
             pointerSatisfied: await anyResolved(greenPointers),
-            sidecarAutoSatisfy: greenSidecarAutoSatisfy
+            phaseEventsSatisfied: phaseEventsAutoSatisfy.green
         }
     };
 }

package/dist/content/core-agents.d.ts

@@ -207,6 +207,20 @@ export declare const CCLAW_AGENTS: readonly [{
     readonly relatedStages: ["tdd"];
     readonly returnSchema: AgentReturnSchema;
     readonly body: string;
+}, {
+    readonly name: "slice-documenter";
+    readonly description: "MANDATORY in PARALLEL with slice-implementer for every TDD slice (regardless of discoveryMode, v6.12.0 Phase R). Writes per-slice prose summary to `<artifacts-dir>/tdd-slices/S-<id>.md`. Does NOT implement, does NOT write tests. Linter rule `tdd_slice_documenter_missing` blocks the gate when a `phase=doc` event is missing for a green slice.";
+    readonly tools: ["Read", "Write", "Edit", "Grep", "Glob"];
+    readonly model: "fast";
+    readonly activation: "mandatory";
+    readonly relatedStages: ["tdd"];
+    readonly returnSchema: {
+        readonly statusField: "status";
+        readonly allowedStatuses: ["DONE", "DONE_WITH_CONCERNS", "NEEDS_CONTEXT", "BLOCKED"];
+        readonly requiredFields: ["status", "summaryMd", "learnings", "evidenceRefs", "blockers"];
+        readonly evidenceFields: ["summaryMd", "evidenceRefs"];
+    };
+    readonly body: string;
 }, {
     readonly name: "fixer";
     readonly description: "ON-DEMAND fresh worker after review FAIL/PARTIAL evidence. Must fix only the cited criterion within explicit allowed files.";

package/dist/content/core-agents.js

@@ -544,6 +544,41 @@ export const CCLAW_AGENTS = [
             "**Role boundary:** do not broaden scope, do not review your own work as final approval, and do not spawn subagents."
         ].join("\n")
     },
+    {
+        name: "slice-documenter",
+        description: "MANDATORY in PARALLEL with slice-implementer for every TDD slice (regardless of discoveryMode, v6.12.0 Phase R). Writes per-slice prose summary to `<artifacts-dir>/tdd-slices/S-<id>.md`. Does NOT implement, does NOT write tests. Linter rule `tdd_slice_documenter_missing` blocks the gate when a `phase=doc` event is missing for a green slice.",
+        tools: ["Read", "Write", "Edit", "Grep", "Glob"],
+        model: "fast",
+        activation: "mandatory",
+        relatedStages: ["tdd"],
+        returnSchema: {
+            statusField: "status",
+            allowedStatuses: ["DONE", "DONE_WITH_CONCERNS", "NEEDS_CONTEXT", "BLOCKED"],
+            requiredFields: ["status", "summaryMd", "learnings", "evidenceRefs", "blockers"],
+            evidenceFields: ["summaryMd", "evidenceRefs"]
+        },
+        body: [
+            "You are a **slice-documenter** dispatched in PARALLEL with `slice-implementer` for the same slice.",
+            "",
+            "**Mission:** capture per-slice prose summary while production code is being written.",
+            "Because your only `claimedPath` is `<artifacts-dir>/tdd-slices/S-<id>.md` and the implementer's `claimedPaths` are production code, the file-overlap scheduler auto-allows the parallel dispatch.",
+            "",
+            "When invoked:",
+            "1. Read the active plan unit, acceptance criterion, and the failing RED test for this slice.",
+            "2. Write a thin per-slice file at `<artifacts-dir>/tdd-slices/S-<id>.md` with the headings:",
+            "   - `# Slice S-<id>`",
+            "   - `## Plan unit` (T-... pointer)",
+            "   - `## Acceptance criteria` (AC-... ids)",
+            "   - `## Why this slice`",
+            "   - `## What was tested`",
+            "   - `## What was implemented`",
+            "   - `## REFACTOR notes`",
+            "   - `## Learnings`",
+            "3. Return JSON: `{ status, summaryMd, learnings: string[], evidenceRefs: [\"<artifacts-dir>/tdd-slices/S-<id>.md\"], blockers: [] }`.",
+            "",
+            "**Forbidden:** edit `06-tdd.md`, test files, or production code. Edit ONLY your slice file."
+        ].join("\n")
+    },
     {
         name: "fixer",
         description: "ON-DEMAND fresh worker after review FAIL/PARTIAL evidence. Must fix only the cited criterion within explicit allowed files.",
@@ -694,7 +729,7 @@ ${(() => {
         const mode = activationModeSummary();
         return `- **Mandatory:** ${mode.mandatory}.
 - **Proactive:** ${mode.proactive}.
-- **On-demand:** slice-implementer, fixer. Research playbooks are in-thread procedures.`;
+- **On-demand:** fixer. Research playbooks are in-thread procedures.`;
     })()}
 
 ### Cost-aware routing

package/dist/content/examples.js

@@ -36,10 +36,10 @@ export const BEHAVIOR_ANCHORS = [
     },
     {
         stage: "tdd",
-        section: "Watched-RED Proof",
-        bad: "Hand-edit `S-1 | 2026-04-15T10:00 | observed RED` into the markdown table; nothing lands in the JSONL sidecar, so retries silently overwrite the row.",
-        good: "Run `cclaw-cli internal tdd-slice-record --slice S-1 --status red --test-file tests/feed.spec.ts --command \"npm test\" --paths src/api/feed.ts --ac AC-3`; the linter reads the sidecar.",
-        ruleHint: "RED/GREEN/REFACTOR transitions are recorded by `cclaw-cli internal tdd-slice-record`; the markdown tables are an auto-derived view from v6.10.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",
@@ -252,7 +252,7 @@ Plan is ready to execute after user confirmation.
 | Slice | Source ID | AC ID | Expected behavior | RED-link |
 | --- | --- | --- | --- | --- |
 | S-1 | SRC-1 | AC-1 | feed window honors 30d cap | spanId:tdd-feed-window-red |
-| S-2 | SRC-2 | AC-3 | degraded banner appears on disconnect | .cclaw/artifacts/06-tdd-slices.jsonl |
+| S-2 | SRC-2 | AC-3 | degraded banner appears on disconnect | spanId:tdd-banner-red (auto-derived from delegation-events.jsonl) |
 
 ## GREEN
 

package/dist/content/hooks.js

@@ -2,7 +2,7 @@ import { existsSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { RUNTIME_ROOT } from "../constants.js";
-import { DELEGATION_DISPATCH_SURFACES, DELEGATION_DISPATCH_SURFACE_PATH_PREFIXES } from "../delegation.js";
+import { DELEGATION_DISPATCH_SURFACES, DELEGATION_DISPATCH_SURFACE_PATH_PREFIXES, DELEGATION_PHASES } from "../delegation.js";
 function resolveCliRuntimeForGeneratedHook() {
     const here = fileURLToPath(import.meta.url);
     // Vitest runs init/sync from src/ and expects helpers to execute the same
@@ -210,6 +210,8 @@ const TERMINAL = new Set(["completed", "failed", "waived", "stale"]);
 const VALID_DISPATCH_SURFACES = ${JSON.stringify([...DELEGATION_DISPATCH_SURFACES])};
 const VALID_DISPATCH_SURFACES_SET = new Set(VALID_DISPATCH_SURFACES);
 const SURFACE_PATH_PREFIXES = ${JSON.stringify(DELEGATION_DISPATCH_SURFACE_PATH_PREFIXES)};
+const VALID_DELEGATION_PHASES = ${JSON.stringify([...DELEGATION_PHASES])};
+const VALID_DELEGATION_PHASES_SET = new Set(VALID_DELEGATION_PHASES);
 const LEDGER_SCHEMA_VERSION = 3;
 const FLOW_STATE_GUARD_REL_PATH = RUNTIME_ROOT + "/.flow-state.guard.json";
 
@@ -343,6 +345,11 @@ function usage() {
     "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)",
+    "",
+    "TDD slice phase tagging (v6.11.0):",
+    "  --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.",
     ""
   ].join("\\n") + "\\n");
 }
@@ -451,6 +458,32 @@ function buildRow(args, status, runId, now, options) {
     .split(",")
     .map((value) => value.trim())
     .filter((value) => value.length > 0);
+  // v6.11.0 (D1+D2): TDD slice tagging via --slice / --phase. Phase
+  // must be one of the canonical enum values; the inline validator
+  // rejects unknown phases before the row hits the ledger.
+  const sliceId =
+    typeof args.slice === "string" && args.slice.trim().length > 0
+      ? args.slice.trim()
+      : undefined;
+  const phase =
+    typeof args.phase === "string" && args.phase.trim().length > 0
+      ? args.phase.trim()
+      : undefined;
+  // v6.11.0 (D2): when --refactor-rationale is supplied it is folded
+  // into evidenceRefs[0] so the linter (which reads evidenceRefs only)
+  // can surface the rationale without touching new fields. The user
+  // may also pass --evidence-ref containing the rationale text.
+  let resolvedEvidenceRefs = normalizeEvidenceRefs(args);
+  if (
+    phase === "refactor-deferred" &&
+    typeof args["refactor-rationale"] === "string" &&
+    args["refactor-rationale"].trim().length > 0
+  ) {
+    const rationale = args["refactor-rationale"].trim();
+    if (!resolvedEvidenceRefs.includes(rationale)) {
+      resolvedEvidenceRefs = [rationale, ...resolvedEvidenceRefs];
+    }
+  }
   return {
     stage: args.stage,
     agent: args.agent,
@@ -463,7 +496,7 @@ function buildRow(args, status, runId, now, options) {
     agentDefinitionPath: args["agent-definition-path"],
     fulfillmentMode,
     waiverReason: args["waiver-reason"],
-    evidenceRefs: normalizeEvidenceRefs(args),
+    evidenceRefs: resolvedEvidenceRefs,
     runId,
     startTs,
     ts: now,
@@ -473,7 +506,9 @@ function buildRow(args, status, runId, now, options) {
     endTs: TERMINAL.has(status) ? now : undefined,
     schemaVersion: LEDGER_SCHEMA_VERSION,
     allowParallel: args["allow-parallel"] === true ? true : undefined,
-    claimedPaths: claimedPaths.length > 0 ? claimedPaths : undefined
+    claimedPaths: claimedPaths.length > 0 ? claimedPaths : undefined,
+    sliceId,
+    phase
   };
 }
 
@@ -1014,6 +1049,36 @@ async function main() {
     return;
   }
 
+  // v6.11.0 (D2) — TDD slice phase tagging validation. --phase is
+  // strictly enum-bound; --slice must be a non-empty string when
+  // provided; --phase=refactor-deferred requires either an explicit
+  // --refactor-rationale or an --evidence-ref with rationale text so
+  // the linter has something to render.
+  if (args.phase !== undefined && !VALID_DELEGATION_PHASES_SET.has(args.phase)) {
+    problems.push("invalid --phase (allowed: " + VALID_DELEGATION_PHASES.join(", ") + ")");
+    emitProblems(problems, json, 2);
+    return;
+  }
+  if (args.slice !== undefined && (typeof args.slice !== "string" || args.slice.trim().length === 0)) {
+    problems.push("--slice requires a non-empty value");
+    emitProblems(problems, json, 2);
+    return;
+  }
+  if (args.phase === "refactor-deferred") {
+    const rationaleProvided =
+      typeof args["refactor-rationale"] === "string" && args["refactor-rationale"].trim().length > 0;
+    const evidenceProvided =
+      (typeof args["evidence-ref"] === "string" && args["evidence-ref"].trim().length > 0) ||
+      (Array.isArray(args["evidence-refs"]) && args["evidence-refs"].some(
+        (ref) => typeof ref === "string" && ref.trim().length > 0
+      ));
+    if (!rationaleProvided && !evidenceProvided) {
+      problems.push("--phase=refactor-deferred requires --refactor-rationale=<text> or --evidence-ref=<text>");
+      emitProblems(problems, json, 2);
+      return;
+    }
+  }
+
   if (args.status === "completed" && args["dispatch-surface"] !== "role-switch") {
     for (const key of ["dispatch-id", "dispatch-surface", "agent-definition-path"]) {
       if (!args[key]) problems.push("completed isolated/generic status requires --" + key);

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.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.
+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,64 @@ 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.**
+
+**Fan-in** — when 2+ \`slice-implementer\` rows complete in a wave, dispatch \`integration-overseer\` to verify cohesion contract (shared types, touchpoints, invariants, integration tests).
+
 `;
 }
 function artifactTemplatePathForStage(stage) {
@@ -593,7 +651,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"
@@ -357,15 +358,12 @@ const REQUIRED_ARTIFACT_SECTIONS = {
     ],
     plan: ["Task List", "Dependency Batches", "Acceptance Mapping", "Execution Posture", "WAIT_FOR_CONFIRM"],
     tdd: [
-        "Test Discovery",
         "System-Wide Impact Check",
         "RED Evidence",
         "GREEN Evidence",
         "REFACTOR Notes",
         "Traceability",
         "Iron Law Acknowledgement",
-        "Watched-RED Proof",
-        "Vertical Slice Cycle",
         "Verification Ladder"
     ],
     review: ["Review Evidence Scope", "Changed-File Coverage", "Layer 1 Verdict", "Review Findings Contract", "Severity Summary", "Final Verdict"],
@@ -724,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/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 {