cclaw-cli 6.13.1 → 6.14.1

package/dist/content/hooks.js

@@ -343,7 +343,8 @@ 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]",
+    "  node .cclaw/hooks/delegation-record.mjs --audit-kind=cclaw_integration_overseer_skipped [--audit-reason=\\\"<comma-separated reasons>\\\"] [--slice-ids=\\\"S-1,S-2\\\"] [--json]    # v6.14.1: emit non-delegation audit row only",
     "",
     "Allowed --dispatch-surface values:",
     "  " + VALID_DISPATCH_SURFACES.join(", "),
@@ -362,12 +363,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");
 }
@@ -538,6 +541,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,
@@ -568,7 +605,9 @@ function buildRow(args, status, runId, now, options) {
     leasedUntil,
     leaseState,
     dependsOn,
-    integrationState
+    integrationState,
+    refactorOutcome,
+    riskTier
   };
 }
 
@@ -860,6 +899,74 @@ async function findLegacyEntry(root, spanId) {
   return ledger.entries.find((entry) => entry && entry.spanId === spanId) || null;
 }
 
+// v6.14.1 — allow-list of non-delegation audit events the controller
+// can emit via the helper. Keep in sync with NON_DELEGATION_AUDIT_EVENTS
+// in src/delegation.ts.
+const VALID_AUDIT_KINDS = new Set([
+  "cclaw_integration_overseer_skipped"
+]);
+
+async function runAuditEmit(args, json) {
+  const kind = String(args["audit-kind"]).trim();
+  if (!VALID_AUDIT_KINDS.has(kind)) {
+    emitProblems([
+      "invalid --audit-kind: " + kind +
+        " (allowed: " + [...VALID_AUDIT_KINDS].join(", ") + ")"
+    ], json, 2);
+    return;
+  }
+  const root = await detectRoot();
+  const runId = await readRunId(root);
+  const reason = typeof args["audit-reason"] === "string"
+    ? args["audit-reason"].trim()
+    : "";
+  const sliceIdsRaw = typeof args["slice-ids"] === "string"
+    ? args["slice-ids"].trim()
+    : "";
+  const sliceIds = sliceIdsRaw.length > 0
+    ? sliceIdsRaw
+      .split(",")
+      .map((value) => value.trim())
+      .filter((value) => value.length > 0)
+    : [];
+  const ts = new Date().toISOString();
+  const payload = {
+    event: kind,
+    runId,
+    ts,
+    eventTs: ts,
+    ...(reason.length > 0 ? { reasons: reason.split(",").map((r) => r.trim()).filter((r) => r.length > 0) } : {}),
+    ...(sliceIds.length > 0 ? { sliceIds } : {})
+  };
+  const stateDir = path.join(root, RUNTIME_ROOT, "state");
+  try {
+    await fs.mkdir(stateDir, { recursive: true });
+    await fs.appendFile(
+      path.join(stateDir, "delegation-events.jsonl"),
+      JSON.stringify(payload) + "\\n",
+      { encoding: "utf8", mode: 0o600 }
+    );
+  } catch (error) {
+    const message = error && typeof error === "object" && "message" in error
+      ? String(error.message)
+      : String(error);
+    emitErrorJson("audit_emit_failed", { kind, message }, json);
+    return;
+  }
+  if (json) {
+    process.stdout.write(JSON.stringify({
+      ok: true,
+      command: "audit-emit",
+      auditKind: kind,
+      runId,
+      sliceIds,
+      ts
+    }, null, 2) + "\\n");
+  } else {
+    process.stdout.write("[cclaw] audit emitted: " + kind + " (run=" + runId + ", ts=" + ts + ")\\n");
+  }
+}
+
 async function runRerecord(args, json) {
   const problems = [];
   for (const key of ["span-id", "dispatch-id", "dispatch-surface", "agent-definition-path"]) {
@@ -1092,6 +1199,18 @@ async function main() {
     return;
   }
 
+  // v6.14.1 — audit-only emit path. When the controller wants to record
+  // a non-delegation audit row (e.g. \`cclaw_integration_overseer_skipped\`
+  // when the wave heuristic chose to skip the overseer dispatch), pass
+  // --audit-kind=<event-name> [--audit-reason=<text>] [--slice-ids=<csv>]
+  // and the helper appends a single line to delegation-events.jsonl
+  // without touching the lifecycle ledger. The kind must be in the
+  // canonical allow-list so a typo cannot inject an unrecognized event.
+  if (typeof args["audit-kind"] === "string" && args["audit-kind"].trim().length > 0) {
+    await runAuditEmit(args, json);
+    return;
+  }
+
   const problems = [];
   if (!args.stage) problems.push("missing --stage");
   if (!args.agent) problems.push("missing --agent");
@@ -1139,6 +1258,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);

package/dist/content/stages/tdd.js

@@ -37,7 +37,11 @@ export const TDD = {
     },
     executionModel: {
         checklist: [
-            "**Wave dispatch (v6.13.1):** Before routing, read the Parallel Execution Plan (managed block in the track planning artifact) and `<artifacts-dir>/wave-plans/`. Multi-ready waves: one AskQuestion (launch wave vs single-slice); then RED checkpoint, parallel GREEN+DOC with worktree-first flags, per-lane REFACTOR. Resume partial waves by parallelizing remaining members only (see top-of-skill `## Wave Batch Mode`).",
+            "**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`).",
+            "**Controller dispatch ordering (v6.14.1 — record BEFORE dispatch).** For every `Task` subagent the controller spawns, record `scheduled` then `launched` ledger events via `node .cclaw/hooks/delegation-record.mjs --status=scheduled ...` and `--status=launched ...` **BEFORE** the `Task(...)` call (one message: ledger writes first, then the matching `Task` calls). Workers self-record `acknowledged` and `completed`; controller back-fill is reserved for `--repair` recovery only. Pass `--span-id`, `--lane-id`, `--claim-token`, `--lease-until` through to the worker so its own helper invocations reuse them.",
+            "**Wave closure — integration-overseer decision (v6.14.1).** When every dispatched lane has a `phase=green status=completed` event AND per-lane REFACTOR coverage is satisfied (separate phase event OR `refactorOutcome` folded into GREEN), call `integrationCheckRequired(events, fanInAudits)` from `src/delegation.ts`. (1) `required: true` → dispatch `integration-overseer` as before. (2) `required: false` → emit the audit row via `node .cclaw/hooks/delegation-record.mjs --audit-kind=cclaw_integration_overseer_skipped --audit-reason=\"<reasons>\" --slice-ids=\"S-1,S-2\" --json` and SKIP the dispatch. Linter advisory `tdd_integration_overseer_skipped_audit_missing` flags a wave that closes without either an overseer dispatch or this audit row.",
+            "**Inline DOC opt-in (v6.14.1 — single-slice non-deep waves).** Default remains parallel `slice-documenter --phase doc` dispatched alongside `slice-implementer --phase green`. For single-slice waves where `flow-state.json::discoveryMode != \"deep\"`, the controller MAY skip the parallel documenter and instead invoke `slice-implementer --finalize-doc --slice S-<id> --paths <artifacts-dir>/tdd-slices/S-<id>.md` synchronously after GREEN. Multi-slice waves and any `discoveryMode=deep` run keep parallel slice-documenter mandatory.",
+            "**Stale active-span recovery (v6.14.1).** If `delegation-record` rejects a new `--status=scheduled` with `dispatch_active_span_collision` or `dispatch_duplicate` and the conflicting span has a `completed` event in `delegation-events.jsonl`, the fold is correct (`computeActiveSubagents` excludes terminal spans) and the rejection is from a different live span on the same `(stage, agent)` pair — pass `--allow-parallel` deliberately, quote the conflicting `spanId` in the turn output, and proceed. If you cannot identify the conflicting active span, STOP and report — do not blanket-add `--allow-parallel` to silence the helper.",
             "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.",
@@ -49,8 +53,8 @@ export const TDD = {
             "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. **Provisional-then-finalize:** append a provisional row/section in `tdd-slices/S-<id>.md` at dispatch time, then finalize that artifact after the matching `phase=green` event records evidence (never treat guesses as final before GREEN lands). Linter rule `tdd_slice_documenter_missing` blocks the gate when the `phase=doc` event is absent (regardless of `discoveryMode`).",
+            "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` `--status=completed` write. Form (3) is the v6.14.0 default for new projects; the linter accepts all three as REFACTOR coverage. Form (1) is the only legal form when BOTH `legacyContinuation: true` AND `flow-state.json::tddCheckpointMode: \"global-red\"` are set (legacy hox-shape projects); other projects may use any form. Set `CCLAW_ACTIVE_AGENT=tdd-refactor` when the harness supports phase labels.",
+            "DOC (v6.14.0+ softened, v6.14.1 inline-opt-in): 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`); the controller MAY either keep parallel `slice-documenter` dispatch (default — preserves the documenter's isolated context) OR, **for single-slice non-deep waves**, call `slice-implementer --finalize-doc --slice S-<id> --paths <artifacts-dir>/tdd-slices/S-<id>.md` inline after GREEN completes. Multi-slice waves keep parallel `slice-documenter` regardless of mode. **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.",
@@ -58,9 +62,9 @@ export const TDD = {
             "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 **only when** the merged wave plan leaves a single scheduler-ready slice or the operator chose single-slice mode. Parallel implementers are allowed 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` (via `delegation-record --audit-kind=cclaw_integration_overseer_skipped --audit-reason=\"<reasons>\"`) 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.",
+            "Controller owns orchestration. **v6.14.1 — record BEFORE dispatch:** every controller `Task` dispatch is preceded by two `delegation-record` writes (`--status=scheduled` then `--status=launched`); workers self-record `--status=acknowledged` on entry and `--status=completed` on exit. Never dispatch first and back-fill — that order breaks the active-span check and forces `--allow-parallel` workarounds. For each slice S-<id>, dispatch in 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 — 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 (mandatory v6.12.0, regardless of `discoveryMode`): in PARALLEL with `slice-implementer --phase green`, dispatch `slice-documenter --slice S-<id> --phase doc` whose only `claimedPaths` is `<artifacts-dir>/tdd-slices/S-<id>.md`. The two dispatches run concurrently because their paths are disjoint. The documenter writes per-slice prose so the main `06-tdd.md` stays thin. Controller MUST NOT author per-slice prose; controller MUST NOT author GREEN production code (use `slice-implementer`).",

package/dist/content/start-command.js

@@ -115,7 +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.13.1):** 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 parallel dispatch for the **remaining** members only (do not restart completed slices).
+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)
 
@@ -208,8 +208,8 @@ 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. **TDD (v6.13.1):** 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:** If a wave is partially closed (some members already past GREEN/REFACTOR), continue with the remaining members in parallel; never redo finished lanes.
+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.

package/dist/delegation.d.ts

@@ -183,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];
@@ -395,6 +424,56 @@ export declare function selectReadySlices(units: ReadySliceUnit[], opts: SelectR
  * 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[]`.
  */

package/dist/delegation.js

@@ -257,7 +257,22 @@ function isDelegationEntry(value) {
             o.integrationState === "applied" ||
             o.integrationState === "conflict" ||
             o.integrationState === "resolved" ||
-            o.integrationState === "abandoned"));
+            o.integrationState === "abandoned") &&
+        (o.refactorOutcome === undefined || isRefactorOutcomeShape(o.refactorOutcome)) &&
+        (o.riskTier === undefined ||
+            o.riskTier === "low" ||
+            o.riskTier === "medium" ||
+            o.riskTier === "high"));
+}
+function isRefactorOutcomeShape(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const o = value;
+    if (o.mode !== "inline" && o.mode !== "deferred")
+        return false;
+    if (o.rationale !== undefined && typeof o.rationale !== "string")
+        return false;
+    return true;
 }
 function isDelegationDispatchSurface(value) {
     return typeof value === "string" && DELEGATION_DISPATCH_SURFACES.includes(value);
@@ -372,7 +387,8 @@ const NON_DELEGATION_AUDIT_EVENTS = new Set([
     "cclaw_fanin_applied",
     "cclaw_fanin_conflict",
     "cclaw_fanin_resolved",
-    "cclaw_fanin_abandoned"
+    "cclaw_fanin_abandoned",
+    "cclaw_integration_overseer_skipped"
 ]);
 function isAuditEventLine(parsed) {
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
@@ -771,6 +787,110 @@ export function readySliceUnitsFromMergedWaves(mergedWaves, planMarkdown, option
     }
     return out;
 }
+export function integrationCheckRequired(events, fanInAudits) {
+    const reasons = [];
+    // Closed slices = ones whose phase=green or phase=refactor row is
+    // completed. We collect each unique sliceId's representative paths
+    // and risk tier so the heuristic looks at terminal state only.
+    const sliceState = new Map();
+    for (const evt of events) {
+        if (evt.stage !== "tdd")
+            continue;
+        if (typeof evt.sliceId !== "string" || evt.sliceId.length === 0)
+            continue;
+        if (evt.status !== "completed")
+            continue;
+        if (evt.phase !== "green" && evt.phase !== "refactor" && evt.phase !== "refactor-deferred") {
+            continue;
+        }
+        const existing = sliceState.get(evt.sliceId) ?? { sliceId: evt.sliceId };
+        if (Array.isArray(evt.claimedPaths) && evt.claimedPaths.length > 0) {
+            const merged = new Set(existing.claimedPaths ?? []);
+            for (const p of evt.claimedPaths)
+                merged.add(p);
+            existing.claimedPaths = [...merged];
+        }
+        if (evt.riskTier === "low" || evt.riskTier === "medium" || evt.riskTier === "high") {
+            // Highest-wins so the verdict is conservative.
+            const order = { low: 0, medium: 1, high: 2 };
+            const prev = existing.riskTier ?? "low";
+            if (order[evt.riskTier] >= order[prev]) {
+                existing.riskTier = evt.riskTier;
+            }
+        }
+        sliceState.set(evt.sliceId, existing);
+    }
+    const slices = [...sliceState.values()];
+    if (slices.some((s) => s.riskTier === "high")) {
+        reasons.push("high-risk-slice");
+    }
+    // Shared-directory heuristic — two distinct slices with overlapping
+    // first-2-segment directory prefixes count as shared boundary.
+    const sliceDirs = new Map();
+    for (const s of slices) {
+        const dirs = new Set();
+        for (const raw of s.claimedPaths ?? []) {
+            const segments = raw.split("/").filter((seg) => seg.length > 0);
+            if (segments.length === 0)
+                continue;
+            // For top-level files like `package.json`, fall back to the
+            // first segment so single-segment paths still count as a shared
+            // directory when two slices both claim the file.
+            const prefix = segments.slice(0, Math.max(1, Math.min(2, segments.length))).join("/");
+            dirs.add(prefix);
+        }
+        if (dirs.size > 0)
+            sliceDirs.set(s.sliceId, dirs);
+    }
+    let sharedFound = false;
+    const ids = [...sliceDirs.keys()];
+    outer: for (let i = 0; i < ids.length; i += 1) {
+        const a = sliceDirs.get(ids[i]);
+        for (let j = i + 1; j < ids.length; j += 1) {
+            const b = sliceDirs.get(ids[j]);
+            for (const dir of a) {
+                if (b.has(dir)) {
+                    sharedFound = true;
+                    break outer;
+                }
+            }
+        }
+    }
+    if (sharedFound)
+        reasons.push("shared-import-boundary");
+    // Fan-in conflict trigger — any `cclaw_fanin_conflict` in the supplied
+    // audits forces the overseer regardless of paths/risk.
+    if (Array.isArray(fanInAudits) && fanInAudits.some((a) => a.event === "cclaw_fanin_conflict")) {
+        reasons.push("fanin-conflict");
+    }
+    if (reasons.length > 0) {
+        return { required: true, reasons };
+    }
+    return { required: false, reasons: ["disjoint-paths"] };
+}
+/**
+ * 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 async function recordIntegrationOverseerSkipped(projectRoot, params) {
+    const eventsPath = delegationEventsPath(projectRoot);
+    const payload = {
+        event: "cclaw_integration_overseer_skipped",
+        runId: params.runId,
+        reasons: params.reasons,
+        sliceIds: params.sliceIds,
+        ts: new Date().toISOString()
+    };
+    try {
+        await fs.mkdir(path.dirname(eventsPath), { recursive: true });
+        await fs.appendFile(eventsPath, `${JSON.stringify(payload)}\n`, "utf8");
+    }
+    catch {
+        // best-effort audit; never block stage advance.
+    }
+}
 /**
  * v6.13.1 — load merged wave plan (Parallel Execution Plan block + wave-plans/) and map to `ReadySliceUnit[]`.
  */

package/dist/flow-state.d.ts

@@ -151,12 +151,57 @@ export interface FlowState {
      * defaults scheduler parallelism to opt-in only for those units.
      */
     legacyContinuation?: boolean;
+    /**
+     * v6.14.0 — TDD wave checkpoint mode (stream-style parallel TDD).
+     *
+     * - `per-slice` — default for new projects. Each lane runs RED→GREEN as
+     *   soon as its `dependsOn` closes; the linter enforces RED-before-GREEN
+     *   per slice only (`tdd_slice_red_completed_before_green`). No global
+     *   barrier between Phase A REDs and Phase B GREENs.
+     * - `global-red` — legacy v6.12/v6.13 behavior. ALL Phase A REDs in a
+     *   wave must complete before ANY Phase B GREEN starts. Auto-applied
+     *   for projects with `legacyContinuation: true` so hox-style runs
+     *   continue to enforce the wave barrier.
+     *
+     * Omitted on legacy state files (treated as `"global-red"` for
+     * `legacyContinuation: true` and `"per-slice"` otherwise via
+     * `effectiveTddCheckpointMode`).
+     */
+    tddCheckpointMode?: "per-slice" | "global-red";
+    /**
+     * v6.14.0 — integration-overseer dispatch mode.
+     *
+     * - `conditional` — default for new projects. The controller calls
+     *   `integrationCheckRequired(events)` after wave closeout; the
+     *   integration-overseer is dispatched only when (a) two or more
+     *   closed slices share import boundaries (heuristic: shared
+     *   directory in `evidenceRefs`/`claimedPaths`), (b) any slice has
+     *   `riskTier === "high"`, or (c) deterministic fan-in reported a
+     *   `cclaw_fanin_conflict`. Otherwise the linter emits the audit
+     *   row `cclaw_integration_overseer_skipped` and skips dispatch.
+     * - `always` — legacy v6.13 behavior. Run integration-overseer
+     *   after every multi-slice wave regardless of trigger.
+     *
+     * Omitted on legacy state files (treated as `"always"`).
+     */
+    integrationOverseerMode?: "conditional" | "always";
 }
 /**
  * Effective worktree mode: legacy state files without the field keep
  * single-tree scheduling to avoid breaking existing runs on upgrade.
  */
 export declare function effectiveWorktreeExecutionMode(state: FlowState): "single-tree" | "worktree-first";
+/**
+ * Effective v6.14 TDD checkpoint mode: legacy state files without the
+ * field default to `global-red` when `legacyContinuation: true` (hox)
+ * and `per-slice` otherwise. Explicit values always win.
+ */
+export declare function effectiveTddCheckpointMode(state: FlowState): "per-slice" | "global-red";
+/**
+ * Effective v6.14 integration-overseer mode: legacy state files without
+ * the field default to `always` (matches v6.13 behavior).
+ */
+export declare function effectiveIntegrationOverseerMode(state: FlowState): "conditional" | "always";
 export interface StageInteractionHint {
     skipQuestions?: boolean;
     sourceStage?: FlowStage;

package/dist/flow-state.js

@@ -51,6 +51,24 @@ export function createInitialCloseoutState() {
 export function effectiveWorktreeExecutionMode(state) {
     return state.worktreeExecutionMode ?? "single-tree";
 }
+/**
+ * Effective v6.14 TDD checkpoint mode: legacy state files without the
+ * field default to `global-red` when `legacyContinuation: true` (hox)
+ * and `per-slice` otherwise. Explicit values always win.
+ */
+export function effectiveTddCheckpointMode(state) {
+    if (state.tddCheckpointMode === "per-slice" || state.tddCheckpointMode === "global-red") {
+        return state.tddCheckpointMode;
+    }
+    return state.legacyContinuation === true ? "global-red" : "per-slice";
+}
+/**
+ * Effective v6.14 integration-overseer mode: legacy state files without
+ * the field default to `always` (matches v6.13 behavior).
+ */
+export function effectiveIntegrationOverseerMode(state) {
+    return state.integrationOverseerMode === "conditional" ? "conditional" : "always";
+}
 export function isFlowTrack(value) {
     return typeof value === "string" && FLOW_TRACKS.includes(value);
 }