cclaw-cli 6.14.0 → 6.14.1

package/dist/artifact-linter/tdd.js

@@ -448,36 +448,69 @@ export async function lintTddStage(ctx) {
         // `integrationCheckRequired()` returns required=false, the gate is
         // soft (advisory) and an audit-only finding is emitted so the
         // controller can record the deliberate skip in artifacts.
+        //
+        // v6.14.1 — also surface the audit row presence. When the controller
+        // skips `integration-overseer` dispatch (or the heuristic returns
+        // false), the run log MUST contain a
+        // `cclaw_integration_overseer_skipped` audit row for traceability.
+        // The advisory `tdd_integration_overseer_skipped_audit_missing`
+        // surfaces a missing audit row when 2+ closed slices closed without
+        // any overseer dispatch AND no audit was recorded.
         let overseerVerdict = null;
         let overseerRequired = true;
+        const skippedAuditRowCount = await countIntegrationOverseerSkippedAudits(projectRoot, delegationLedger.runId);
+        const skippedAuditRowFound = skippedAuditRowCount > 0;
         if (integrationOverseerMode === "conditional") {
             const eventsForVerdict = runEvents.length > 0 ? runEvents : [];
             const auditsForVerdict = fanInAudits.filter((a) => a.runId === delegationLedger.runId);
             overseerVerdict = integrationCheckRequired(eventsForVerdict, auditsForVerdict);
             overseerRequired = overseerVerdict.required;
             if (!overseerVerdict.required) {
+                const auditRowSuffix = skippedAuditRowFound
+                    ? "audit row recorded — skip is fully traceable."
+                    : "audit row MISSING — controller should append `cclaw_integration_overseer_skipped` for traceability (see `tdd_integration_overseer_skipped_audit_missing`).";
                 findings.push({
                     section: "tdd_integration_overseer_skipped_by_disjoint_paths",
                     required: false,
-                    rule: "v6.14.0 conditional integration-overseer mode: the heuristic returned `required: false` (disjoint claimedPaths, no high-risk slices, no fan-in conflicts). The controller may skip dispatching `integration-overseer` and emit a `cclaw_integration_overseer_skipped` audit row instead.",
+                    rule: "v6.14.0+ conditional integration-overseer mode: the heuristic returned `required: false` (disjoint claimedPaths, no high-risk slices, no fan-in conflicts). The controller may skip dispatching `integration-overseer` and emit a `cclaw_integration_overseer_skipped` audit row instead.",
                     found: true,
-                    details: `integrationCheckRequired() reasons: ${overseerVerdict.reasons.join(", ")}. Skip is safe — record an audit row via delegation events for traceability.`
+                    details: `integrationCheckRequired() reasons: ${overseerVerdict.reasons.join(", ")}. Skip is safe — ${auditRowSuffix}`
                 });
             }
         }
+        // v6.14.1 — `tdd_integration_overseer_skipped_audit_missing` (advisory).
+        // Fires when fan-out is detected (2+ completed slice-implementers),
+        // no `integration-overseer` was dispatched at all (no scheduled or
+        // completed row for the active run), AND no
+        // `cclaw_integration_overseer_skipped` audit row exists. This pairs
+        // with the controller skill text rule that the wave-closure decision
+        // ("dispatch overseer or skip") MUST leave a trail.
+        const overseerDispatched = activeRunEntries.some((entry) => entry.agent === "integration-overseer");
+        if (!overseerDispatched && !skippedAuditRowFound) {
+            findings.push({
+                section: "tdd_integration_overseer_skipped_audit_missing",
+                required: false,
+                rule: "v6.14.1: when a wave with 2+ closed slices closes without any integration-overseer dispatch, the controller should call `integrationCheckRequired()` and emit a `cclaw_integration_overseer_skipped` audit row so the decision is traceable. Advisory — never blocks stage-complete.",
+                found: false,
+                details: `Fan-out detected (${completedSliceImplementers.length} completed slice-implementer rows) but no integration-overseer dispatch row OR cclaw_integration_overseer_skipped audit row exists for active run. ` +
+                    "Remediation: emit `node .cclaw/hooks/delegation-record.mjs --audit-kind=cclaw_integration_overseer_skipped --audit-reason=\"<reasons>\" --slice-ids=\"<S-1,S-2,...>\"` after wave closure."
+            });
+        }
         findings.push({
             section: "tdd.integration_overseer_missing",
             required: overseerRequired,
             rule: overseerRequired
                 ? "When fan-out is detected, require completed `integration-overseer` evidence with PASS or PASS_WITH_GAPS."
-                : "v6.14.0 conditional integration-overseer mode: integration-overseer dispatch is advisory because `integrationCheckRequired()` returned required=false. Run it anyway if the run touches new boundaries.",
+                : "v6.14.0+ conditional integration-overseer mode: integration-overseer dispatch is advisory because `integrationCheckRequired()` returned required=false. Run it anyway if the run touches new boundaries.",
             found: integrationOverseerFound,
             details: integrationOverseerFound
                 ? "integration-overseer completion recorded with PASS/PASS_WITH_GAPS evidence."
                 : completedOverseerRows.length === 0
                     ? overseerRequired
                         ? "Fan-out detected but no completed integration-overseer delegation row exists for active run."
-                        : "Fan-out detected; integration-overseer not dispatched (conditional mode skipped on disjoint paths). Audit-only."
+                        : skippedAuditRowFound
+                            ? "Fan-out detected; integration-overseer not dispatched (conditional mode skipped on disjoint paths) and `cclaw_integration_overseer_skipped` audit row recorded. Audit-only."
+                            : "Fan-out detected; integration-overseer not dispatched (conditional mode skipped on disjoint paths). Audit-only."
                     : "integration-overseer completion exists, but PASS/PASS_WITH_GAPS evidence is missing in delegation evidenceRefs and artifact text."
         });
     }
@@ -551,6 +584,46 @@ export async function lintTddStage(ctx) {
         }
     }
 }
+/**
+ * v6.14.1 — count `cclaw_integration_overseer_skipped` audit rows in
+ * `delegation-events.jsonl` for a given runId. The audit row is not a
+ * `DelegationEvent` (no agent/status), so `readDelegationEvents`
+ * filters it out; we re-scan the raw file with a narrow JSON match.
+ *
+ * Best-effort: missing file or parse errors return 0.
+ */
+async function countIntegrationOverseerSkippedAudits(projectRoot, runId) {
+    const filePath = path.join(projectRoot, ".cclaw/state/delegation-events.jsonl");
+    let raw = "";
+    try {
+        raw = await fs.readFile(filePath, "utf8");
+    }
+    catch {
+        return 0;
+    }
+    let count = 0;
+    for (const line of raw.split(/\r?\n/u)) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            continue;
+        const obj = parsed;
+        if (obj.event !== "cclaw_integration_overseer_skipped")
+            continue;
+        if (typeof obj.runId === "string" && obj.runId !== runId)
+            continue;
+        count += 1;
+    }
+    return count;
+}
 async function listSliceFiles(slicesDir) {
     let entries = [];
     try {

package/dist/content/core-agents.js

@@ -52,6 +52,56 @@ Before doing substantive work, return an ACK object that the parent can record:
 
 Finish with the required return schema plus the same \`spanId\` and \`dispatchId\`. The parent must not claim isolated completion unless ACK/result proof matches the ledger/event span.`;
 }
+/**
+ * v6.14.1 — TDD worker self-record contract. The parent records
+ * `scheduled` and `launched` rows BEFORE dispatching the Task; the
+ * worker is responsible for `acknowledged` (on entry) and `completed`
+ * (on exit). This contract restores the v6.13.1 discipline that
+ * v6.14.0 dropped — the controller-side fix in v6.14.1's TDD skill
+ * text is paired with this worker-side self-record helper template.
+ */
+function tddWorkerSelfRecordContract(agentName) {
+    const isImplementer = agentName === "slice-implementer";
+    const refactorOutcomeFlag = isImplementer
+        ? " --refactor-outcome=inline|deferred [--refactor-rationale=\"<why>\"]"
+        : "";
+    const laneFlags = isImplementer
+        ? " [--claim-token=<t>] [--lane-id=<lane>] [--lease-until=<iso>]"
+        : "";
+    return `## TDD Worker Self-Record Contract (v6.14.1)
+
+You are a TDD worker dispatched via \`Task\`. The parent already wrote your \`scheduled\` and \`launched\` ledger rows BEFORE invoking you. **Your responsibility is to self-record \`acknowledged\` on entry and \`completed\` on exit** by invoking \`.cclaw/hooks/delegation-record.mjs\` directly. Do NOT skip these — the controller depends on them, the linter validates them, and back-fill via \`--repair\` is reserved for recovery only.
+
+**On entry — record acknowledgement (BEFORE doing work):**
+
+\`\`\`bash
+ACK_TS="$(date -u +%Y-%m-%dT%H:%M:%S.%3NZ 2>/dev/null || date -u +%Y-%m-%dT%H:%M:%SZ)"
+node .cclaw/hooks/delegation-record.mjs \\
+  --stage=tdd --agent=${agentName} --mode=mandatory \\
+  --status=acknowledged \\
+  --span-id=<spanId from controller dispatch> \\
+  --dispatch-id=<dispatchId from controller dispatch> \\
+  --dispatch-surface=<surface from controller dispatch> \\
+  --agent-definition-path=.cclaw/agents/${agentName}.md \\
+  --ack-ts="$ACK_TS" \\
+  --json
+\`\`\`
+
+**On exit — record completion (AFTER work + verification):**
+
+\`\`\`bash
+COMPLETED_TS="$(date -u +%Y-%m-%dT%H:%M:%S.%3NZ 2>/dev/null || date -u +%Y-%m-%dT%H:%M:%SZ)"
+node .cclaw/hooks/delegation-record.mjs \\
+  --stage=tdd --agent=${agentName} --mode=mandatory \\
+  --status=completed \\
+  --span-id=<same spanId> \\
+  --completed-ts="$COMPLETED_TS" \\
+  --evidence-ref="<test-path-or-artifact-ref>"${refactorOutcomeFlag}${laneFlags} \\
+  --json
+\`\`\`
+
+Reuse the same \`<spanId>\` and \`<dispatchId>\` across both rows. \`--ack-ts\` and \`--completed-ts\` must be monotonic on the span (\`startTs ≤ launchedTs ≤ ackTs ≤ completedTs\`); the helper rejects out-of-order writes with \`delegation_timestamp_non_monotonic\`. If the helper rejects with \`dispatch_active_span_collision\` against a stale span, surface the conflicting \`spanId\` to the parent — do NOT silently retry with \`--allow-parallel\`.`;
+}
 function formatReturnSchema(schema) {
     const lines = [
         `- Status field: \`${schema.statusField}\``,
@@ -600,6 +650,18 @@ export const CCLAW_AGENTS = [
         ].join("\n")
     }
 ];
+/**
+ * v6.14.1 — agents whose rendered `.cclaw/agents/<name>.md` file gets the
+ * TDD worker self-record helper template. These agents are the ones the
+ * controller dispatches via `Task` during a TDD wave; they are
+ * responsible for `acknowledged` and `completed` ledger writes.
+ */
+const TDD_WORKER_SELF_RECORD_AGENTS = new Set([
+    "test-author",
+    "slice-implementer",
+    "slice-documenter",
+    "integration-overseer"
+]);
 import { stageDelegationSummary } from "./stage-schema.js";
 /**
  * Render a complete cclaw agent markdown file (YAML frontmatter + body).
@@ -627,6 +689,9 @@ export function agentMarkdown(agent) {
     ].join("\n");
     const relatedStages = agent.relatedStages.length > 0 ? agent.relatedStages.join(", ") : "(none)";
     const taskDelegation = defaultTaskDelegationSection(agent.name);
+    const tddWorkerSelfRecordSection = TDD_WORKER_SELF_RECORD_AGENTS.has(agent.name)
+        ? `\n${tddWorkerSelfRecordContract(agent.name)}\n`
+        : "";
     return `${frontmatter}
 
 # ${agent.name}
@@ -639,7 +704,7 @@ ${agent.body}
 - Related stages: ${relatedStages}
 
 ${workerAckContract()}
-
+${tddWorkerSelfRecordSection}
 ## Required Return Schema
 
 STRICT_RETURN_SCHEMA: return a structured object matching this contract before any narrative when delegated. Include \`spanId\`, \`dispatchId\` or \`workerRunId\`, \`dispatchSurface\`, \`agentDefinitionPath\`, and lifecycle timestamps when provided by the parent.

package/dist/content/hooks.js

@@ -344,6 +344,7 @@ function 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 --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(", "),
@@ -898,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"]) {
@@ -1130,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");

package/dist/content/stages/tdd.js

@@ -38,6 +38,10 @@ export const TDD = {
     executionModel: {
         checklist: [
             "**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 (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.",
+            "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 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.",
+            "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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cclaw-cli",
-  "version": "6.14.0",
+  "version": "6.14.1",
   "description": "Installer-first flow toolkit for coding agents",
   "type": "module",
   "bin": {