cclaw-cli 6.13.0 → 6.14.0

package/dist/artifact-linter.js

@@ -1,7 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { resolveArtifactPath as resolveStageArtifactPath } from "./artifact-paths.js";
-import { effectiveWorktreeExecutionMode } from "./flow-state.js";
+import { effectiveIntegrationOverseerMode, effectiveTddCheckpointMode, effectiveWorktreeExecutionMode } from "./flow-state.js";
 import { exists } from "./fs-utils.js";
 import { stageSchema } from "./content/stage-schema.js";
 import { readFlowState } from "./run-persistence.js";
@@ -124,6 +124,8 @@ export async function lintArtifact(projectRoot, stage, track = "standard", optio
     let completedStageMetaForAudit;
     let legacyContinuation = false;
     let worktreeExecutionMode = "single-tree";
+    let tddCheckpointMode = "per-slice";
+    let integrationOverseerMode = "always";
     try {
         const flowState = await readFlowState(projectRoot);
         const hint = flowState.interactionHints?.[stage];
@@ -136,6 +138,8 @@ export async function lintArtifact(projectRoot, stage, track = "standard", optio
         completedStageMetaForAudit = flowState.completedStageMeta;
         legacyContinuation = flowState.legacyContinuation === true;
         worktreeExecutionMode = effectiveWorktreeExecutionMode(flowState);
+        tddCheckpointMode = effectiveTddCheckpointMode(flowState);
+        integrationOverseerMode = effectiveIntegrationOverseerMode(flowState);
     }
     catch {
         activeStageFlags = [];
@@ -146,6 +150,8 @@ export async function lintArtifact(projectRoot, stage, track = "standard", optio
         completedStageMetaForAudit = undefined;
         legacyContinuation = false;
         worktreeExecutionMode = "single-tree";
+        tddCheckpointMode = "per-slice";
+        integrationOverseerMode = "always";
     }
     for (const extra of options.extraStageFlags ?? []) {
         if (typeof extra === "string" && extra.length > 0 && !activeStageFlags.includes(extra)) {
@@ -283,7 +289,9 @@ export async function lintArtifact(projectRoot, stage, track = "standard", optio
         activeStageFlags,
         taskClass,
         legacyContinuation,
-        worktreeExecutionMode
+        worktreeExecutionMode,
+        tddCheckpointMode,
+        integrationOverseerMode
     };
     switch (stage) {
         case "brainstorm":

package/dist/content/hooks.js

@@ -294,6 +294,19 @@ async function readRunId(root) {
   }
 }
 
+async function readWorktreeExecutionModeInline(root) {
+  try {
+    const raw = await fs.readFile(path.join(root, RUNTIME_ROOT, "state", "flow-state.json"), "utf8");
+    const parsed = JSON.parse(raw);
+    if (parsed && parsed.worktreeExecutionMode === "worktree-first") {
+      return "worktree-first";
+    }
+    return "single-tree";
+  } catch {
+    return "single-tree";
+  }
+}
+
 async function readDelegationEvents(root) {
   try {
     const raw = await fs.readFile(path.join(root, RUNTIME_ROOT, "state", "delegation-events.jsonl"), "utf8");
@@ -330,7 +343,7 @@ function usage() {
     "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] [--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]",
+    "  node .cclaw/hooks/delegation-record.mjs --repair --span-id=<id> --repair-reason=\\\"<why>\\\" [--json]",
     "",
     "Allowed --dispatch-surface values:",
     "  " + VALID_DISPATCH_SURFACES.join(", "),
@@ -349,12 +362,14 @@ function usage() {
     "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.",
+    "  --refactor-rationale=<t>  required when --phase=refactor-deferred unless --evidence-ref carries the rationale text. v6.14.0: also paired with --refactor-outcome on phase=green.",
     "  --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.",
+    "  --refactor-outcome=<m>   v6.14.0 — one of inline|deferred. Folds REFACTOR into the phase=green event so a single row can close RED→GREEN→REFACTOR. Pair --refactor-outcome=deferred with --refactor-rationale.",
+    "  --risk-tier=<t>          v6.14.0 — one of low|medium|high. high triggers integration-overseer in conditional mode.",
     ""
   ].join("\\n") + "\\n");
 }
@@ -525,6 +540,40 @@ function buildRow(args, status, runId, now, options) {
       : undefined;
   const leaseState =
     leasedUntil && status === "scheduled" ? "claimed" : undefined;
+  // v6.14.0: refactorOutcome folds REFACTOR into a phase=green event. We
+  // also accept it on phase=refactor / phase=refactor-deferred for forward
+  // compatibility with controllers that emit it on the legacy lifecycle.
+  // When mode=deferred and a --refactor-rationale is supplied we also
+  // mirror the rationale into evidenceRefs[0] so legacy linters keep
+  // reading evidence (matches the v6.11.0 refactor-deferred behavior).
+  const refactorOutcomeMode =
+    typeof args["refactor-outcome"] === "string"
+      ? args["refactor-outcome"].trim()
+      : "";
+  let refactorOutcome;
+  if (refactorOutcomeMode === "inline" || refactorOutcomeMode === "deferred") {
+    const rationaleRaw =
+      typeof args["refactor-rationale"] === "string"
+        ? args["refactor-rationale"].trim()
+        : "";
+    refactorOutcome = {
+      mode: refactorOutcomeMode,
+      ...(rationaleRaw.length > 0 ? { rationale: rationaleRaw } : {})
+    };
+    if (
+      refactorOutcomeMode === "deferred" &&
+      rationaleRaw.length > 0 &&
+      !resolvedEvidenceRefs.includes(rationaleRaw)
+    ) {
+      resolvedEvidenceRefs = [rationaleRaw, ...resolvedEvidenceRefs];
+    }
+  }
+  const riskTierRaw =
+    typeof args["risk-tier"] === "string" ? args["risk-tier"].trim() : "";
+  const riskTier =
+    riskTierRaw === "low" || riskTierRaw === "medium" || riskTierRaw === "high"
+      ? riskTierRaw
+      : undefined;
   return {
     stage: args.stage,
     agent: args.agent,
@@ -555,7 +604,9 @@ function buildRow(args, status, runId, now, options) {
     leasedUntil,
     leaseState,
     dependsOn,
-    integrationState
+    integrationState,
+    refactorOutcome,
+    riskTier
   };
 }
 
@@ -1126,6 +1177,44 @@ async function main() {
     }
   }
 
+  // v6.14.0 — --refactor-outcome must be one of inline|deferred. When
+  // mode=deferred a rationale is required (either --refactor-rationale or
+  // --evidence-ref carrying the rationale text). --risk-tier must be one of
+  // low|medium|high if provided.
+  if (
+    args["refactor-outcome"] !== undefined &&
+    args["refactor-outcome"] !== "inline" &&
+    args["refactor-outcome"] !== "deferred"
+  ) {
+    problems.push("invalid --refactor-outcome (allowed: inline, deferred)");
+    emitProblems(problems, json, 2);
+    return;
+  }
+  if (args["refactor-outcome"] === "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("--refactor-outcome=deferred requires --refactor-rationale=<text> or --evidence-ref=<text>");
+      emitProblems(problems, json, 2);
+      return;
+    }
+  }
+  if (
+    args["risk-tier"] !== undefined &&
+    args["risk-tier"] !== "low" &&
+    args["risk-tier"] !== "medium" &&
+    args["risk-tier"] !== "high"
+  ) {
+    problems.push("invalid --risk-tier (allowed: low, medium, high)");
+    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);
@@ -1265,6 +1354,33 @@ async function main() {
     }
   }
 
+  if (
+    clean.stage === "tdd" &&
+    clean.agent === "slice-implementer" &&
+    clean.phase === "green" &&
+    (await readWorktreeExecutionModeInline(root)) === "worktree-first"
+  ) {
+    const tok = typeof clean.claimToken === "string" ? clean.claimToken.trim() : "";
+    const lane = typeof clean.ownerLaneId === "string" ? clean.ownerLaneId.trim() : "";
+    const lease = typeof clean.leasedUntil === "string" ? clean.leasedUntil.trim() : "";
+    if (tok.length === 0 || lane.length === 0 || lease.length === 0) {
+      const missing = [];
+      if (tok.length === 0) missing.push("--claim-token");
+      if (lane.length === 0) missing.push("--lane-id");
+      if (lease.length === 0) missing.push("--lease-until");
+      emitErrorJson(
+        "dispatch_lane_metadata_missing",
+        {
+          missing,
+          remediation:
+            "worktree-first mode requires --claim-token, --lane-id, and --lease-until on every slice-implementer --phase green delegation-record write (from scheduled through completed)."
+        },
+        json
+      );
+      return;
+    }
+  }
+
   await persistEntry(root, runId, clean, event);
   process.stdout.write(JSON.stringify({ ok: true, event }, null, 2) + "\\n");
 }

package/dist/content/skills.js

@@ -4,6 +4,7 @@ import { FLOW_STAGES } from "../types.js";
 import { behaviorAnchorFor, stageExamples } from "./examples.js";
 import { INVESTIGATION_DISCIPLINE_BLOCK } from "./templates.js";
 import { reviewStackAwareRoutes, reviewStackAwareRoutingSummary, stageAutoSubagentDispatch, stageSchema, stageTrackRenderContext } from "./stage-schema.js";
+import { renderTrackTerminology } from "./track-render-context.js";
 import { referencePatternsForStage } from "./reference-patterns.js";
 import { harnessDelegationRecipes } from "../harness-adapters.js";
 const VERIFICATION_STAGES = ["tdd", "review", "ship"];
@@ -196,16 +197,20 @@ ONE slice = THREE dispatches, in this order. Do not skip, do not collapse.
    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>'\`.
 
+**Rule 1 (v6.13.1):** Before any slice-routing question, read \`<artifacts-dir>/05-plan.md\` (managed \`## Parallel Execution Plan\`) **and** list \`<artifacts-dir>/wave-plans/wave-NN.md\`. Merge mentally: Parallel Execution Plan first, wave files second; duplicate slices with conflicting wave membership are invalid. If the merged plan shows a wave with **two or more** scheduler-ready slices, issue **exactly one** \`AskQuestion\`: \`Launch wave W-NN with N parallel lanes (S-a, S-b, ...)?\` with default option **launch wave** and alternate **single-slice instead**. Do not ask "which slice next?" when that question is redundant (single ready slice or no wave). After **launch wave** confirmation, execute RED checkpoint → parallel GREEN+DOC → per-lane REFACTOR without further routing asks. After **single-slice instead**, fall back to the legacy single-slice ritual. **Wave dispatch resume:** if part of the wave is already done, parallelize only the remaining members.
+
 **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\`.
+Delegation-record signature (extend with lane metadata for every GREEN row in \`worktree-first\`):
+
+\`node .cclaw/hooks/delegation-record.mjs --stage=tdd --agent=slice-implementer --mode=mandatory --status=scheduled --span-id=<id> --dispatch-id=<id> --dispatch-surface=<surface> --agent-definition-path=<path> --slice=S-1 --phase=green --paths=src/a.ts --claim-token=<opaque> --lane-id=<lane> --lease-until=<iso8601> --json\`
 
-## Wave Batch Mode (v6.12.0+)
+## Wave Batch Mode (v6.13.1+)
 
-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\`.
+**Triggers:** managed \`## Parallel Execution Plan\` in \`05-plan.md\` **or** any \`<artifacts-dir>/wave-plans/wave-NN.md\`, OR 2+ slices with disjoint \`claimedPaths\`. Cap = 5 \`slice-implementer\` lanes (10 subagents incl. paired documenters) via \`MAX_PARALLEL_SLICE_IMPLEMENTERS\`. **Preconditions:** Load both sources before routing. Worktree-first: every GREEN delegation-record MUST include \`--claim-token\`, \`--lane-id\`, \`--lease-until\` (hook exits \`2\`, \`dispatch_lane_metadata_missing\` otherwise).
 
 **Phase A — RED checkpoint** — ONE message, all test-authors:
 \`\`\`
@@ -215,20 +220,18 @@ 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:
+**Phase B — GREEN+DOC fan-out** — ONE message; pair per slice (repeat for each lane, flags unique per lane):
+
 \`\`\`
-Task("slice-implementer --slice S-1 --phase green --paths <S-1 prod>")
+Task("slice-implementer --slice S-1 --phase green --paths <prod> --claim-token=<t> --lane-id=<lane-1> --lease-until=<iso>")
 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).
+Launch every slice's pair in that same message. **Never serialize independent work.**
 
-**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.
+**Phase C — REFACTOR per slice** — after GREEN+DOC lands, dispatch refactor/refactor-deferred per slice. **Fan-in (worktree-first):** echo claim/lane/lease on completed GREEN rows; stage-complete runs deterministic \`git apply --3way\` (no \`-X ours/theirs\`). Conflicts: \`slice-implementer --phase resolve-conflict\`. With 2+ lanes, still dispatch \`integration-overseer\` before review.
 
-**slice-documenter** may mark prose \`provisional\` until GREEN is proven; finalize \`tdd-slices/S-<id>.md\` after GREEN evidence is recorded.
+**slice-documenter:** record the \`phase=doc\` row in the same message as GREEN; write a **provisional** row in \`tdd-slices/S-<id>.md\` immediately at dispatch, then **finalize** that file after the matching \`slice-implementer\` \`phase=green\` event lands (evidence-backed prose, not guesswork before GREEN exists).
 
 `;
 }
@@ -655,7 +658,7 @@ If you are about to violate the Iron Law, STOP. No amount of urgency, partial pr
 
 </EXTREMELY-IMPORTANT>
 
-${tddTopOfSkillBlock(stage)}${quickStartBlock(stage, track)}
+${renderTrackTerminology(tddTopOfSkillBlock(stage), trackContext)}${quickStartBlock(stage, track)}
 
 ${STAGE_LANGUAGE_POLICY_POINTER}
 ## Philosophy

package/dist/content/stages/tdd.js

@@ -37,29 +37,29 @@ export const TDD = {
     },
     executionModel: {
         checklist: [
-            "Select vertical slice — pick one source item from the active track (plan task on standard/medium, spec AC or bug reproduction slice on quick). Do not batch multiple tasks. Before starting, read `.cclaw/state/ralph-loop.json` (`loopIteration`, `acClosed[]`, `redOpenSlices[]`) so you skip cycles already closed. If `redOpenSlices[]` is non-empty, repair or explicitly park those slices before opening a new RED.",
+            "**Stream-style wave dispatch (v6.14.0):** Before routing, read the Parallel Execution Plan (managed block in the track planning artifact) and `<artifacts-dir>/wave-plans/`. Per-lane stream: each lane runs RED→GREEN→REFACTOR independently as soon as its `dependsOn` closes — no global RED checkpoint between Phase A and Phase B. The linter enforces RED-before-GREEN per slice via `tdd_slice_red_completed_before_green`; cross-lane interleaving is allowed. **Legacy `global-red` mode** is preserved for projects with `legacyContinuation: true` and any project that explicitly sets `flow-state.json::tddCheckpointMode: \"global-red\"` (rule `tdd_red_checkpoint_violation` still fires there). Multi-ready waves still get one AskQuestion (launch wave vs single-slice); then per-lane GREEN+DOC dispatch with worktree-first flags. Integration-overseer fires only on cross-slice trigger (see `integrationCheckRequired()` heuristic). Resume partial waves by parallelizing remaining members only (see top-of-skill `## Wave Batch Mode`).",
+            "Select vertical slice — the active wave plan (or single ready slice) defines work. Do not ask \"which slice next?\" when the plan already resolves it. Before starting, read `.cclaw/state/ralph-loop.json` (`loopIteration`, `acClosed[]`, `redOpenSlices[]`) so you skip cycles already closed. If `redOpenSlices[]` is non-empty, repair or explicitly park those slices before opening a new RED.",
             "Map to acceptance criterion — identify the specific spec criterion this test proves.",
             "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.",
             "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.",
+            "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. When `flow-state.json::worktreeExecutionMode` is `worktree-first`, **mandatory** flags on every GREEN delegation-record row: `--claim-token=<opaque> --lane-id=<lane> --lease-until=<iso8601>`. Attach an evidence ref 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: 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, 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.",
+            "REFACTOR (v6.14.0 — three forms): (1) re-dispatch `slice-implementer` with `--phase refactor` after GREEN; (2) re-dispatch with `--phase refactor-deferred --refactor-rationale \"<why>\"` to close without a separate pass; (3) **fold REFACTOR into GREEN** by adding `--refactor-outcome=inline|deferred [--refactor-rationale=\"<why>\"]` on the same `slice-implementer --phase green` dispatch. Form (3) is the v6.14.0 default; the linter accepts all three as REFACTOR coverage. Set `CCLAW_ACTIVE_AGENT=tdd-refactor` when the harness supports phase labels.",
+            "DOC (v6.14.0 — softened): in `discoveryMode=deep` runs DOC remains mandatory — 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 parallel dispatch. **In `lean` and `guided` modes DOC is advisory** (linter `tdd_slice_documenter_missing` becomes `required: false`); controllers may either keep parallel `slice-documenter` dispatch or call `slice-implementer --finalize-doc` inline at GREEN-completion. **Provisional-then-finalize still applies for parallel dispatch:** append a provisional row/section in `tdd-slices/S-<id>.md` at dispatch time, then finalize after the matching `phase=green` event records evidence.",
             "**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).",
-            "Repeat for each slice — return to step 1 for the next plan slice."
+            "Repeat for each slice — when not in multi-slice wave mode, return to wave-plan discovery; otherwise continue the active wave until members close.",
         ],
         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 (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.",
+            "Pick one vertical slice at a time **only when** the merged wave plan leaves a single scheduler-ready slice or the operator chose single-slice mode. Parallel implementers are allowed when lanes touch non-overlapping files (the file-overlap scheduler auto-allows parallel when `--paths` are disjoint). **Integration-overseer is conditional in v6.14.0** (see `flow-state.json::integrationOverseerMode`): with the default `\"conditional\"` it dispatches only when `integrationCheckRequired()` returns `required: true` (shared import boundaries between closed slices, any slice with `riskTier=high`, or a recorded `cclaw_fanin_conflict`). When the heuristic returns `required: false`, record an audit `cclaw_integration_overseer_skipped` and let the linter emit advisory `tdd_integration_overseer_skipped_by_disjoint_paths`. Projects with `legacyContinuation: true` or explicit `\"always\"` keep the v6.13.x mandatory dispatch.",
+            "Slice implementers are sequential only when the plan serializes work; prefer wave-parallel GREEN+DOC when the Parallel Execution Plan marks multiple ready members.",
             "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.",

package/dist/content/start-command.js

@@ -115,6 +115,7 @@ If during any stage the agent discovers evidence that contradicts the initial Ph
 2. If flow state is missing → guide the user to run \`npx cclaw-cli init\` and stop.
 3. If flow state is only a fresh init placeholder (\`completedStages: []\`, all \`passed\` arrays empty, and no \`00-idea.md\`) → stop and ask for \`/cc <prompt>\` to start a tracked run. Do not create a brainstorm state implicitly.
 4. Otherwise check current stage gates, resume if incomplete, and advance if complete.
+5. **TDD wave dispatch (v6.14.0 — stream-style):** When \`currentStage\` is \`tdd\`, read \`${RUNTIME_ROOT}/artifacts/05-plan.md\` Parallel Execution Plan block and \`${RUNTIME_ROOT}/artifacts/wave-plans/\` **before** any slice-routing question. If an open wave still has multiple ready slices, resume per-lane stream dispatch for the **remaining** members only (do not restart completed slices). **No global RED checkpoint barrier** in default \`tddCheckpointMode: "per-slice"\` — each lane advances RED→GREEN→REFACTOR as soon as its \`dependsOn\` closes; the linter enforces RED-before-GREEN per slice. Projects with \`legacyContinuation: true\` or explicit \`tddCheckpointMode: "global-red"\` retain the v6.13.x global barrier.
 
 ## Headless mode (CI/automation only)
 
@@ -207,9 +208,11 @@ Progress the tracked flow only when one exists:
 2. If missing, guide the user to run \`npx cclaw-cli init\` and stop.
 3. If it is only a fresh init placeholder (\`completedStages: []\`, no passed gates, and no \`${RUNTIME_ROOT}/artifacts/00-idea.md\`), stop and ask for \`/cc <prompt>\` to start a tracked run. Do not silently create a brainstorm run.
 4. Check gates for \`currentStage\`.
-5. If incomplete → load current stage skill and execute.
-6. If complete → advance to next stage and execute.
-7. If flow is done → report completion.
+5. **TDD (v6.14.0 — stream-style):** When \`currentStage\` is \`tdd\`, read \`${RUNTIME_ROOT}/artifacts/05-plan.md\` (managed \`## Parallel Execution Plan\` between \`parallel-exec-managed\` markers) and scan \`${RUNTIME_ROOT}/artifacts/wave-plans/wave-NN.md\` **before** asking which slice runs next. Merge sources in controller memory: Parallel Execution Plan first, wave files second; the same slice must not disagree across sources.
+6. **Wave dispatch resume (per-lane stream):** If a wave is partially closed (some members already past GREEN/REFACTOR), continue with the remaining members in parallel as soon as their \`dependsOn\` closes — do **not** wait for a global RED-completion barrier in default \`tddCheckpointMode: "per-slice"\`. Never redo finished lanes. Integration-overseer fires only on cross-slice trigger (default \`integrationOverseerMode: "conditional"\`); skipped dispatches must record audit \`cclaw_integration_overseer_skipped\`.
+7. If incomplete → load current stage skill and execute.
+8. If complete → advance to next stage and execute.
+9. If flow is done → report completion.
 
 ## Public flow habit
 

package/dist/delegation.d.ts

@@ -2,6 +2,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 ParseImplementationUnitParallelOptions, type ParsedParallelWave } from "./internal/plan-split-waves.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"];
@@ -182,6 +183,35 @@ export type DelegationEntry = {
      * v6.13.0 — integration branch merge status after deterministic fan-in.
      */
     integrationState?: "pending" | "applied" | "conflict" | "resolved" | "abandoned";
+    /**
+     * v6.14.0 — refactor outcome folded into `phase=green` events so a single
+     * row can close RED→GREEN→REFACTOR for the slice without a separate
+     * `phase=refactor` / `phase=refactor-deferred` lifecycle pass.
+     *
+     * - `mode: "inline"` — refactor pass ran inline as part of the GREEN
+     *   delegation (rationale optional but recommended for traceability).
+     * - `mode: "deferred"` — refactor was intentionally deferred; rationale
+     *   is required (carried in `rationale` and mirrored into
+     *   `evidenceRefs[0]` so legacy linters that read evidence still work).
+     *
+     * `phase=refactor` and `phase=refactor-deferred` events remain valid
+     * for backward compatibility; the linter accepts either form for
+     * REFACTOR coverage.
+     *
+     * keep in sync with the inline copy in
+     * `src/content/hooks.ts::delegationRecordScript`.
+     */
+    refactorOutcome?: {
+        mode: "inline" | "deferred";
+        rationale?: string;
+    };
+    /**
+     * v6.14.0 — risk tier hint copied from the plan slice. Used by
+     * `integrationCheckRequired()` to decide whether the
+     * integration-overseer must run. `low` and `medium` are advisory;
+     * `high` always triggers the overseer. Optional on every row.
+     */
+    riskTier?: "low" | "medium" | "high";
 };
 export declare const DELEGATION_PHASES: readonly ["red", "green", "refactor", "refactor-deferred", "doc", "resolve-conflict"];
 export type DelegationPhase = (typeof DELEGATION_PHASES)[number];
@@ -390,6 +420,64 @@ export interface SelectReadySlicesOptions {
  * `claimedPaths` intersections with already-selected units and active holders.
  */
 export declare function selectReadySlices(units: ReadySliceUnit[], opts: SelectReadySlicesOptions): ReadySliceUnit[];
+/**
+ * v6.13.1 — build scheduler rows from merged parallel wave definitions + plan units.
+ */
+export declare function readySliceUnitsFromMergedWaves(mergedWaves: ParsedParallelWave[], planMarkdown: string, options?: ParseImplementationUnitParallelOptions): ReadySliceUnit[];
+/**
+ * v6.14.0 — verdict from `integrationCheckRequired()`.
+ *
+ * `required: true` means the controller MUST dispatch
+ * `integration-overseer` before stage-complete; `reasons[]` lists the
+ * triggers that fired so the controller can quote them in artifacts.
+ *
+ * `required: false` means the integration check can be safely skipped
+ * (disjoint paths, no high-risk slices, no fan-in conflicts). Callers
+ * that skip dispatch should append a `cclaw_integration_overseer_skipped`
+ * audit row to `delegation-events.jsonl` so the run log stays honest
+ * about the decision.
+ */
+export interface IntegrationCheckVerdict {
+    required: boolean;
+    reasons: string[];
+}
+/**
+ * v6.14.0 — heuristic helper deciding whether a multi-slice wave needs
+ * the `integration-overseer` dispatch.
+ *
+ * Triggers (any one):
+ *   - **two or more closed slices share import boundaries** (heuristic:
+ *     two slices declare a `claimedPaths` whose first 2 path segments
+ *     match — same package/module directory);
+ *   - any slice has `riskTier === "high"`;
+ *   - any `cclaw_fanin_conflict` audit row exists in the supplied
+ *     events list (regardless of slice).
+ *
+ * When none fire, the verdict is `{ required: false, reasons: ["disjoint-paths"] }`
+ * and the caller should record a `cclaw_integration_overseer_skipped`
+ * audit before bypassing the dispatch.
+ *
+ * Note on inputs: this function reads from the supplied delegation
+ * events list directly so callers can inject synthetic data in tests.
+ * Use `readDelegationEvents(projectRoot)` in production paths.
+ */
+export declare function integrationCheckRequired(events: DelegationEvent[]): IntegrationCheckVerdict;
+export declare function integrationCheckRequired(events: DelegationEvent[], fanInAudits: FanInAuditRecord[]): IntegrationCheckVerdict;
+/**
+ * v6.14.0 — append a non-delegation audit event recording that the
+ * integration-overseer dispatch was skipped because
+ * `integrationCheckRequired()` returned `required: false`. Best-effort;
+ * never throws.
+ */
+export declare function recordIntegrationOverseerSkipped(projectRoot: string, params: {
+    runId: string;
+    reasons: string[];
+    sliceIds: string[];
+}): Promise<void>;
+/**
+ * v6.13.1 — load merged wave plan (Parallel Execution Plan block + wave-plans/) and map to `ReadySliceUnit[]`.
+ */
+export declare function loadTddReadySlicePool(planMarkdown: string, artifactsDir: string, options?: ParseImplementationUnitParallelOptions): Promise<ReadySliceUnit[]>;
 /**
  * v6.10.0 (P1) — when scheduling a `slice-implementer` on a TDD stage,
  * compare `claimedPaths` against every currently active span on the