cclaw-cli 6.9.0 → 6.11.0

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: "PARALLEL with slice-implementer in TDD GREEN. Writes per-slice prose summary to `<artifacts-dir>/tdd-slices/S-<id>.md`. Does NOT implement, does NOT write tests. Mandatory on discoveryMode=deep, opt-in elsewhere.";
+    readonly tools: ["Read", "Write", "Edit", "Grep", "Glob"];
+    readonly model: "fast";
+    readonly activation: "on-demand";
+    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: "PARALLEL with slice-implementer in TDD GREEN. Writes per-slice prose summary to `<artifacts-dir>/tdd-slices/S-<id>.md`. Does NOT implement, does NOT write tests. Mandatory on discoveryMode=deep, opt-in elsewhere.",
+        tools: ["Read", "Write", "Edit", "Grep", "Glob"],
+        model: "fast",
+        activation: "on-demand",
+        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.",

package/dist/content/examples.js

@@ -36,10 +36,10 @@ export const BEHAVIOR_ANCHORS = [
     },
     {
         stage: "tdd",
-        section: "RED Evidence",
-        bad: "RED: `expect(true).toBe(true)` then \"failing test observed\" — the assertion can never have caught the bug it claims to prove.",
-        good: "RED: `expect(api.fetchFeed()).rejects.toThrow(AuthError)`; the failure output names the missing guard and ties to AC-3.",
-        ruleHint: "Mental mutation test: name a plausible bug that would still pass the assertion. If you can, the assertion is too coarse."
+        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."
     },
     {
         stage: "review",
@@ -247,12 +247,12 @@ Plan is ready to execute after user confirmation.
 | S-1 feed window | expected 30d window, got 7d |
 | S-2 degraded banner | banner absent after forced disconnect |
 
-## Acceptance Mapping
+## Acceptance & Failure Map
 
-| Slice | AC IDs |
-| --- | --- |
-| S-1 | AC-1 |
-| S-2 | AC-3 |
+| 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 | 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";
 
@@ -326,7 +328,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 +341,15 @@ 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)",
+    "",
+    "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");
 }
@@ -440,6 +451,39 @@ 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);
+  // 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,
@@ -452,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,
@@ -461,7 +505,10 @@ 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,
+    sliceId,
+    phase
   };
 }
 
@@ -502,6 +549,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;
@@ -906,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);
@@ -992,6 +1165,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.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.
 `;
 }
 /**

package/dist/content/stage-schema.js

@@ -357,15 +357,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"],

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.",
-            "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.",
+            "Use the mandatory `test-author` delegation for RED — after discovery and impact check, dispatch with `--slice S-<id> --phase red`. Produce failing behavior tests only (no production edits) and let the harness record the dispatch via the generated `delegation-record` hook. Set `CCLAW_ACTIVE_AGENT=tdd-red` when the harness supports phase labels.",
+            "RED: do NOT hand-edit `## Watched-RED Proof`, `## Vertical Slice Cycle`, or `## RED Evidence` markdown tables. The linter auto-renders them from `delegation-events.jsonl` slice phase rows; manual edits inside the auto-render markers are overwritten on the next lint.",
+            "Dispatch the `slice-implementer` for GREEN with `--slice S-<id> --phase green` and explicit `--paths` so the file-overlap scheduler can auto-allow parallel slices. Attach an evidence ref (test path, span ref, or pasted-output pointer) so the Vertical Slice Cycle row is well-formed. Set `CCLAW_ACTIVE_AGENT=tdd-green` when the harness supports phase labels.",
             "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.",
+            "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.",
             "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.",
@@ -58,10 +58,11 @@ export const TDD = {
         ],
         interactionProtocol: [
             "Pick one vertical slice at a time: source item, RED test, GREEN implementation, REFACTOR, and verification evidence move together.",
-            "Slice implementers are sequential by default. Parallel implementers are allowed only when (a) lanes touch non-overlapping files, (b) the controller passes `--allow-parallel` on each ledger row, and (c) an `integration-overseer` is dispatched after the parallel lanes and writes cohesion-evidence into the artifact before the gate is marked passed.",
-            "Controller owns orchestration; one mandatory `test-author` delegation carries phase-specific RED -> GREEN -> REFACTOR evidence instead of spawning separate workers by default.",
+            "Slice implementers are sequential by default. Parallel implementers are allowed only when (a) lanes touch non-overlapping files (the file-overlap scheduler auto-allows parallel when `--paths` are disjoint), and (b) an `integration-overseer` is dispatched after the parallel lanes and writes cohesion-evidence into the artifact before the gate is marked passed.",
+            "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.",
             "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.",
@@ -104,20 +105,20 @@ export const TDD = {
             { id: "tdd_docs_drift_check", description: "When public API/config/CLI surfaces change, docs drift is addressed via a completed doc-updater pass." }
         ],
         requiredEvidence: [
-            "Artifact updated at `.cclaw/artifacts/06-tdd.md` with Test Discovery, System-Wide Impact Check, RED, GREEN, and REFACTOR sections.",
+            "Artifact updated at `.cclaw/artifacts/06-tdd.md` with System-Wide Impact Check, Acceptance & Failure Map, REFACTOR Notes, Iron Law Acknowledgement, Verification Ladder, and Learnings.",
             "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.",
-            "Failing command output captured (RED).",
-            "Full test/build output recorded (GREEN).",
+            "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.",
+            "REFACTOR observability: per slice, a `phase=refactor` event OR a `phase=refactor-deferred` event whose evidenceRefs / refactor rationale captures why refactor was deferred.",
             "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`.",
-            "Watched-RED Proof includes at least one populated row with an ISO timestamp.",
-            "Vertical Slice Cycle records RED, GREEN, and REFACTOR per active slice.",
             "Acceptance mapping documented.",
             "Failure reason analysis recorded.",
             "Refactor rationale captured.",
-            "Traceability to task identifier is documented."
+            "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."
         ],
         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"],
@@ -156,18 +157,16 @@ export const TDD = {
         },
         artifactValidation: [
             { 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: "Test Discovery", required: false, validationRule: "Overall narrative for how the stage discovered the existing test surface. Per-slice details live under `tdd-slices/S-<id>.md` from v6.11.0; the `## Test Discovery` heading is optional/advisory." },
             { 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: "GREEN Evidence", required: true, validationRule: "Full suite pass output captured." },
+            { section: "RED Evidence", required: true, validationRule: "Failing test output per slice. From v6.11.0 this section is auto-satisfied by a `phase=red` event in `delegation-events.jsonl` with non-empty evidenceRefs; the markdown block remains required as a legacy fallback when phase events are absent." },
+            { section: "Acceptance & Failure Map", required: false, validationRule: "Each slice row carries Source ID, AC ID, expected behavior, and a RED-link (delegation spanId or evidence path). From v6.11.0 the column is auto-derivable from `phase=red` events." },
+            { section: "GREEN Evidence", required: true, validationRule: "Full suite pass output. From v6.11.0 this section is auto-satisfied by a `phase=green` event in `delegation-events.jsonl` with non-empty evidenceRefs; the markdown block remains required as a legacy fallback when phase events are absent." },
             { section: "REFACTOR Notes", required: true, validationRule: "What changed, why, behavior preservation confirmed." },
             { section: "Traceability", required: true, validationRule: "Plan task ID and spec criterion linked." },
             { section: "Iron Law Acknowledgement", required: true, validationRule: "Must include `Acknowledged: yes` and list exceptions (or `None`)." },
-            { section: "Watched-RED Proof", required: true, validationRule: "At least one populated row with ISO timestamp proving RED was observed before production edits." },
-            { section: "Vertical Slice Cycle", required: true, validationRule: "Per active slice records RED, GREEN, and REFACTOR timestamps (refactor may be deferred only with explicit rationale)." },
+            { section: "Watched-RED Proof", required: false, validationRule: "From v6.11.0 the Watched-RED summary is auto-rendered from `delegation-events.jsonl` slice phase events (see auto-start: tdd-slice-summary marker). Legacy markdown tables continue to validate via the fallback path." },
+            { section: "Vertical Slice Cycle", required: false, validationRule: "From v6.11.0 the Vertical Slice Cycle table is auto-rendered between `auto-start: tdd-slice-summary` markers. Legacy markdown tables continue to validate via the fallback path." },
             { section: "Verification Ladder", required: true, validationRule: "Per-slice verification tier (static, command, behavioral, human) with evidence captured for the highest tier reached this turn. Must include command + PASS/FAIL + commit SHA when VCS is present, or explicit no-vcs reason plus content/artifact hash/config override." },
             { section: "TDD Blocker Taxonomy", required: false, validationRule: "When blocked, classify as NO_SOURCE_CONTEXT, NO_TEST_SURFACE, NO_IMPLEMENTABLE_SLICE, RED_NOT_EXPRESSIBLE, or NO_VCS_MODE; include blockedBecause, missingInputs, recommendedRoute, nextCommand, and resumeCriteria." },
             { section: "Coverage Targets", required: false, validationRule: "If present: per-module or per-code-type coverage thresholds with current values and measurement commands." },
@@ -302,11 +301,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 or evidence path). From v6.11.0 a `phase=red` event in `delegation-events.jsonl` with non-empty evidenceRefs satisfies the row."
                     };
                 }
                 if (row.section === "Traceability") {

package/dist/content/subagents.js

@@ -676,9 +676,9 @@ function sliceImplementerEnhancedBody() {
 ${MARKDOWN_CODE_FENCE}
 You are a slice-implementer subagent.
 
-SLICE: {single vertical slice}
+SLICE: {single vertical slice — controller MUST dispatch you with --slice S-<id> --phase green --paths <comma-separated>}
 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 phase-event contract (v6.11.0):
+- Do NOT hand-edit \`## Watched-RED Proof\`, \`## Vertical Slice Cycle\`, \`## RED Evidence\`, or \`## GREEN Evidence\` markdown tables in 06-tdd.md. The linter auto-renders them between \`<!-- auto-start: tdd-slice-summary -->\` markers from \`delegation-events.jsonl\` slice phase rows.
+- Your dispatch row IS the evidence: the harness-generated delegation-record hook stamps \`sliceId=S-<id>\`, \`phase=green\`, and \`completedTs\` automatically. Attach evidenceRefs (test path, span ref, or pasted-output pointer) so the linter validates the row.
+- After REFACTOR, ask the controller to re-dispatch you with \`--phase refactor\` (or \`--phase refactor-deferred --refactor-rationale "<why>"\`); each call appends a new ledger row.
+- Per-slice prose summary lives in \`<artifacts-dir>/tdd-slices/S-<id>.md\` and is owned by the parallel \`slice-documenter\` (or the controller). You do NOT touch that file.
 ${MARKDOWN_CODE_FENCE}
 
 `;
@@ -929,12 +935,15 @@ FIXTURES / PATTERNS: {links to helper modules by path + naming conventions}
 
 Process (mandatory):
 1) If STAGE_MODE=TEST_RED_ONLY:
-   - RED only — add failing tests proving the gap (show failing output excerpt).
+   - Controller dispatched you with \`--slice S-<id> --phase red\`. Add failing tests proving the gap (show failing output excerpt).
    - Do NOT edit production code.
+   - Do NOT hand-edit \`## Watched-RED Proof\` / \`## RED Evidence\` markdown tables in 06-tdd.md — the linter auto-renders them from your dispatch row in \`delegation-events.jsonl\`. Just ensure your worker return includes evidenceRefs (test path, span ref, or pasted-output pointer) so the harness can stamp them on the ledger row.
    - Report: TESTS_ADDED, RED_COMMAND_RUN, RED_EVIDENCE, STATUS: DONE|BLOCKED.
 2) If STAGE_MODE=BUILD_GREEN_REFACTOR:
+   - Controller dispatched you with \`--slice S-<id> --phase green\` (and later \`--phase refactor\` or \`--phase refactor-deferred --refactor-rationale "<why>"\`).
    - GREEN — minimal production code to satisfy existing RED tests, rerun full suite.
    - REFACTOR — only after full suite is green; preserve behavior.
+   - Do NOT hand-edit \`## Vertical Slice Cycle\` / \`## GREEN Evidence\` markdown tables — auto-rendered from your dispatch row.
    - Report: FILES_EDITED, GREEN_COMMAND_RUN, REFACTOR_NOTES, STATUS: DONE|BLOCKED.
 ${MARKDOWN_CODE_FENCE}
 

package/dist/content/templates.d.ts

@@ -17,4 +17,10 @@ export declare const RULEBOOK_MARKDOWN = "# Cclaw Rulebook\n\n## MUST_ALWAYS\n-
  */
 export declare const CURSOR_GUIDELINES_RULE_MDC = "---\ndescription: cclaw zero-install behavior baseline (always-on)\nglobs:\n  - \"**/*\"\nalwaysApply: true\n---\n\n<!-- cclaw-managed-cursor-guidelines-rule -->\n\n# Cclaw Baseline Guidelines\n\nThese three rules apply to every Cursor agent session in this project,\nregardless of whether stage skills loaded.\n\n## 1. Q&A floor before drafting (brainstorm/scope/design)\n\nBefore drafting any `.cclaw/artifacts/01-brainstorm-*.md`,\n`02-scope-*.md`, or `03-design-*.md`, verify that the artifact's\n`## Q&A Log` table demonstrates Ralph-Loop convergence: every\nforcing-question topic id is tagged `[topic:<id>]` on at least one row\n(see the stage's forcing-questions checklist for the id list), the last\n2 turns produce no new decision-changing impact, OR an explicit user\nstop-signal row is recorded. Walk the stage forcing questions one at a\ntime via the `AskQuestion` tool. If you find yourself proposing a\ndraft after 1-2 questions while forcing topic ids remain untagged, STOP\nand continue the loop.\n\nThe `qa_log_unconverged` linter rule will block `stage-complete` when\nconvergence has not been reached. Wave 24 (v6.0.0) made `[topic:<id>]`\ntagging mandatory; the English keyword fallback was removed because it\nmis-reported convergence on RU/UA Q&A logs.\n\n## 2. Mandatory subagents run after Q&A approval\n\nFor brainstorm / scope / design, mandatory subagents (\n`product-discovery`, `critic`, `planner`, `architect`,\n`test-author`) run **only AFTER the user approves the elicitation\noutcome**, never before the Q&A loop converges. Dispatching them early\npreempts the user dialogue and violates the elicitation contract \u2014 the\nlinter will block stage-complete.\n\nSee each stage's \"Run Phase: post-elicitation\" rows in the materialized\nAutomatic Subagent Dispatch table.\n\n## 3. Never echo cclaw command lines to chat\n\nThe user does not run cclaw helpers (`node .cclaw/hooks/...`) manually.\nNEVER paste full command lines, `--evidence-json '{...}'` payloads,\n`--waive-delegation=...`, or shell hash commands (`shasum`,\n`sha256sum`, `Get-FileHash`, `certutil`, etc.) into chat. Run the\nhelper via the tool layer and report only the resulting summary. On\nfailure, report a compact human-readable summary plus the helper JSON in\na single fenced `json` block.\n";
 export declare const CURSOR_WORKFLOW_RULE_MDC = "---\ndescription: cclaw workflow guardrails for Cursor agent sessions\nglobs:\n  - \"**/*\"\nalwaysApply: true\n---\n\n<!-- cclaw-managed-cursor-workflow-rule -->\n\n# Cclaw Workflow Guardrails\n\n## Activation Rule\n\nBefore responding to coding work:\n1. Read `.cclaw/state/flow-state.json`.\n2. Start with `/cc` or continue with `/cc`.\n3. If no software-stage flow applies, respond normally.\n\n## Stage Order\n\n`brainstorm -> scope -> design -> spec -> plan -> tdd -> review -> ship`\n\nTrack-specific skips are allowed only when `flow-state.track` + `skippedStages` explicitly say so.\n\n## Task Classification\n\n| Class | Route |\n|---|---|\n| non-trivial software work | `/cc <idea>` |\n| trivial software fix | `/cc <idea>` (quick track) |\n| bugfix with repro | `/cc <idea>` and enforce RED-first in tdd |\n| pure question / non-software | direct answer (no stage flow) |\n\n## Command Surface\n\n- `/cc` = entry and resume.\n- `/cc` = only progression path.\n- Knowledge capture and recall use the `learnings` skill when requested.\n\n## Verification Discipline\n\n- No completion claim without fresh command evidence in this turn.\n- Stage completion claim requires `stage-complete` exit 0 in the current turn. Quote the single-line success JSON printed to stdout (e.g. `{\"ok\":true,\"command\":\"stage-complete\",...}`); do not paraphrase, do not infer success from empty stdout or from skipped retries.\n\n## Protocol label hygiene\n\n`skip` wording means different things depending on phase: brainstorm/scope/design Q&A stop-signals may still literal **skip**/enough/move-on wording; structured ship closeout retros and compound clustering prompts should expose **no changes** (or accept-as-is language) rather than labeling the passive path as skip. Keep the verbs aligned with the harness question copy you present to the human.\n- Do not mark gates passed from memory.\n- Keep evidence in `.cclaw/artifacts/`; archive through closeout via `/cc` or cancel early via `node .cclaw/hooks/cancel-run.mjs`.\n\n## Delegation And Approvals\n\n- Machine-only checks in design/plan/tdd/review/ship should auto-dispatch when tooling supports it.\n- **For brainstorm / scope / design stages**: ask user input continuously via adaptive elicitation (one question per turn through the harness-native question tool \u2014 `AskQuestion` in Cursor). Walk the stage forcing-questions list one-by-one. **Tag each Q&A Log row's `Decision impact` cell with `[topic:<id>]`** (the id is given in the stage's forcing-questions checklist) so the linter can verify coverage in any natural language. Do NOT batch and do NOT defer to a single approval gate at the end. The `qa_log_unconverged` linter rule will block `stage-complete` when convergence is not reached (forcing topic ids untagged AND last 2 turns still produce decision-changing rows AND no stop-signal).\n- **For other stages** (spec/plan/tdd/build/review/ship): ask user input only at explicit approval gates (scope mode, plan approval, challenge resolution, ship finalization), not for routine progress updates.\n- If you find yourself proposing a draft after 1-2 questions in brainstorm/scope/design, STOP \u2014 go back to the forcing-questions list and continue.\n- Mandatory subagents in brainstorm/scope/design run only AFTER the user approves the elicitation outcome (see each stage's \"Run Phase: post-elicitation\" rows). Dispatching them before the Q&A loop converges violates the contract.\n- Never echo cclaw command lines (`node .cclaw/hooks/...`, `--evidence-json '{...}'`) to chat \u2014 the user does not run cclaw manually. Run helpers via the tool layer; report only the resulting summary.\n- If harness capabilities are partial, record waiver reasons in delegation logs.\n\n## Routing Source Of Truth\n\n- Primary router: `.cclaw/skills/using-cclaw/SKILL.md`.\n- Stage behavior: current stage skill plus `.cclaw/state/flow-state.json`.\n- Preamble budget: keep role/status announcements brief and avoid repeating\n  them unless the stage or role changes.\n";
+/**
+ * v6.11.0 (S2) — per-slice prose file written by `slice-documenter`
+ * (or the controller) to `<artifacts-dir>/tdd-slices/S-<id>.md`. The
+ * main `06-tdd.md` is auto-indexed via `## Slices Index`.
+ */
+export declare function tddSliceFileTemplate(sliceId: string): string;
 export declare function buildRulesJson(): Record<string, unknown>;