cclaw-cli 6.11.0 → 6.13.0

package/dist/delegation.js

@@ -8,6 +8,8 @@ import { exists, withDirectoryLock, writeFileSafe } from "./fs-utils.js";
 import { HARNESS_ADAPTERS } from "./harness-adapters.js";
 import { readFlowState } from "./runs.js";
 import { mandatoryAgentsFor, stageSchema } from "./content/stage-schema.js";
+import { effectiveWorktreeExecutionMode } from "./flow-state.js";
+import { compareCanonicalUnitIds } from "./internal/plan-split-waves.js";
 const execFileAsync = promisify(execFile);
 const TERMINAL_DELEGATION_STATUSES = new Set(["completed", "failed", "waived", "stale"]);
 export const DELEGATION_DISPATCH_SURFACES = [
@@ -43,7 +45,8 @@ export const DELEGATION_PHASES = [
     "green",
     "refactor",
     "refactor-deferred",
-    "doc"
+    "doc",
+    "resolve-conflict"
 ];
 export const DELEGATION_LEDGER_SCHEMA_VERSION = 3;
 function delegationLogPath(projectRoot) {
@@ -238,7 +241,23 @@ function isDelegationEntry(value) {
             (typeof o.sliceId === "string" && o.sliceId.length > 0)) &&
         (o.phase === undefined ||
             (typeof o.phase === "string" &&
-                DELEGATION_PHASES.includes(o.phase))));
+                DELEGATION_PHASES.includes(o.phase))) &&
+        (o.claimToken === undefined || typeof o.claimToken === "string") &&
+        (o.ownerLaneId === undefined || typeof o.ownerLaneId === "string") &&
+        (o.leasedUntil === undefined || typeof o.leasedUntil === "string") &&
+        (o.leaseState === undefined ||
+            o.leaseState === "claimed" ||
+            o.leaseState === "expired" ||
+            o.leaseState === "released" ||
+            o.leaseState === "reclaimed") &&
+        (o.dependsOn === undefined ||
+            (Array.isArray(o.dependsOn) && o.dependsOn.every((item) => typeof item === "string"))) &&
+        (o.integrationState === undefined ||
+            o.integrationState === "pending" ||
+            o.integrationState === "applied" ||
+            o.integrationState === "conflict" ||
+            o.integrationState === "resolved" ||
+            o.integrationState === "abandoned"));
 }
 function isDelegationDispatchSurface(value) {
     return typeof value === "string" && DELEGATION_DISPATCH_SURFACES.includes(value);
@@ -348,7 +367,12 @@ export async function readDelegationLedger(projectRoot) {
 const NON_DELEGATION_AUDIT_EVENTS = new Set([
     "mandatory_delegations_skipped_by_track",
     "artifact_validation_demoted_by_track",
-    "expansion_strategist_skipped_by_track"
+    "expansion_strategist_skipped_by_track",
+    "cclaw_slice_lease_expired",
+    "cclaw_fanin_applied",
+    "cclaw_fanin_conflict",
+    "cclaw_fanin_resolved",
+    "cclaw_fanin_abandoned"
 ]);
 function isAuditEventLine(parsed) {
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
@@ -356,13 +380,47 @@ function isAuditEventLine(parsed) {
     const evt = parsed.event;
     return typeof evt === "string" && NON_DELEGATION_AUDIT_EVENTS.has(evt);
 }
+const FAN_IN_AUDIT_EVENT_KINDS = new Set([
+    "cclaw_fanin_applied",
+    "cclaw_fanin_conflict",
+    "cclaw_fanin_resolved",
+    "cclaw_fanin_abandoned"
+]);
+function isFanInAuditRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const o = value;
+    const evt = o.event;
+    if (typeof evt !== "string" || !FAN_IN_AUDIT_EVENT_KINDS.has(evt)) {
+        return false;
+    }
+    return typeof o.ts === "string" && o.ts.length > 0;
+}
+/**
+ * Append a deterministic fan-in audit row (not a delegation lifecycle event).
+ */
+export async function recordCclawFanInAudit(projectRoot, params) {
+    const filePath = delegationEventsPath(projectRoot);
+    const payload = {
+        event: params.kind,
+        runId: params.runId,
+        laneId: params.laneId,
+        sliceIds: params.sliceIds,
+        integrationBranch: params.integrationBranch,
+        details: params.details,
+        ts: new Date().toISOString()
+    };
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.appendFile(filePath, `${JSON.stringify(payload)}\n`, { encoding: "utf8", mode: 0o600 });
+}
 export async function readDelegationEvents(projectRoot) {
     const filePath = delegationEventsPath(projectRoot);
     if (!(await exists(filePath))) {
-        return { events: [], corruptLines: [] };
+        return { events: [], corruptLines: [], fanInAudits: [] };
     }
     const events = [];
     const corruptLines = [];
+    const fanInAudits = [];
     const text = await fs.readFile(filePath, "utf8").catch(() => "");
     const lines = text.split(/\r?\n/gu);
     for (let index = 0; index < lines.length; index += 1) {
@@ -374,6 +432,9 @@ export async function readDelegationEvents(projectRoot) {
             if (isDelegationEvent(parsed)) {
                 events.push(parsed);
             }
+            else if (isFanInAuditRecord(parsed)) {
+                fanInAudits.push(parsed);
+            }
             else if (isAuditEventLine(parsed)) {
                 // Wave 24 audit-only row (e.g. mandatory_delegations_skipped_by_track).
                 // Not a delegation lifecycle event but valid audit content.
@@ -387,7 +448,7 @@ export async function readDelegationEvents(projectRoot) {
             corruptLines.push(index + 1);
         }
     }
-    return { events, corruptLines };
+    return { events, corruptLines, fanInAudits };
 }
 async function appendDelegationEvent(projectRoot, event) {
     const filePath = delegationEventsPath(projectRoot);
@@ -605,12 +666,70 @@ export class DispatchCapError extends Error {
         this.pair = params.pair;
     }
 }
+/**
+ * v6.13.0 — claim / lease contract violation for worktree-first TDD rows.
+ */
+export class DispatchClaimInvalidError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "DispatchClaimInvalidError";
+    }
+}
 /**
  * v6.10.0 (P2) — default cap on active `slice-implementer` spans in a
  * single TDD run. Aligned with evanflow's parallel cap. Override via
  * `CCLAW_MAX_PARALLEL_SLICE_IMPLEMENTERS=<int>` (validated `>=1`).
  */
 export const MAX_PARALLEL_SLICE_IMPLEMENTERS = 5;
+/**
+ * Return up to `cap` slice units whose dependsOn are satisfied, avoiding
+ * `claimedPaths` intersections with already-selected units and active holders.
+ */
+export function selectReadySlices(units, opts) {
+    const pool = opts.legacyContinuation ? units.filter((u) => u.parallelizable) : units;
+    const ordered = [...pool].sort((a, b) => compareCanonicalUnitIds(a.unitId, b.unitId));
+    const selected = [];
+    const blockedPaths = new Set();
+    for (const holder of opts.activePathHolders) {
+        for (const p of holder.paths) {
+            blockedPaths.add(p);
+        }
+    }
+    for (const u of ordered) {
+        if (opts.completedUnitIds.has(u.unitId))
+            continue;
+        if (!u.dependsOn.every((d) => opts.completedUnitIds.has(d)))
+            continue;
+        let clash = false;
+        for (const p of u.claimedPaths) {
+            if (blockedPaths.has(p)) {
+                clash = true;
+                break;
+            }
+        }
+        if (clash)
+            continue;
+        for (const v of selected) {
+            for (const pu of u.claimedPaths) {
+                if (v.claimedPaths.includes(pu)) {
+                    clash = true;
+                    break;
+                }
+            }
+            if (clash)
+                break;
+        }
+        if (clash)
+            continue;
+        selected.push(u);
+        for (const p of u.claimedPaths) {
+            blockedPaths.add(p);
+        }
+        if (selected.length >= opts.cap)
+            break;
+    }
+    return selected;
+}
 function readMaxParallelOverrideFromEnv() {
     const raw = process.env.CCLAW_MAX_PARALLEL_SLICE_IMPLEMENTERS;
     if (typeof raw !== "string" || raw.trim().length === 0)
@@ -740,8 +859,45 @@ async function writeSubagentTracker(projectRoot, entries) {
     }));
     await writeFileSafe(subagentsStatePath(projectRoot), `${JSON.stringify({ active, updatedAt: new Date().toISOString() }, null, 2)}\n`, { mode: 0o600 });
 }
+function latestClaimTokenForSpan(entries, spanId) {
+    if (!spanId)
+        return null;
+    let latest = null;
+    for (const e of entries) {
+        if (e.spanId !== spanId)
+            continue;
+        if (typeof e.claimToken === "string" && e.claimToken.trim().length > 0) {
+            latest = e.claimToken.trim();
+        }
+    }
+    return latest;
+}
+function assertSliceClaimInvariant(flow, stamped, prior) {
+    if (stamped.stage !== "tdd" || stamped.agent !== "slice-implementer")
+        return;
+    if (effectiveWorktreeExecutionMode(flow) !== "worktree-first")
+        return;
+    if (stamped.status === "scheduled" && typeof stamped.sliceId === "string" && stamped.sliceId.length > 0) {
+        const tok = stamped.claimToken?.trim() ?? "";
+        if (tok.length === 0) {
+            throw new DispatchClaimInvalidError("dispatch_claim_invalid — worktree-first requires --claim-token when scheduling slice-implementer with --slice");
+        }
+    }
+    if (!TERMINAL_DELEGATION_STATUSES.has(stamped.status))
+        return;
+    if (stamped.status === "waived" || stamped.status === "stale")
+        return;
+    const expected = latestClaimTokenForSpan(prior, stamped.spanId);
+    if (!expected)
+        return;
+    const got = stamped.claimToken?.trim() ?? "";
+    if (got !== expected) {
+        throw new DispatchClaimInvalidError("dispatch_claim_invalid — claimToken must match the scheduled claim for this span");
+    }
+}
 export async function appendDelegation(projectRoot, entry) {
-    const { activeRunId } = await readFlowState(projectRoot);
+    const flowState = await readFlowState(projectRoot);
+    const { activeRunId } = flowState;
     await withDirectoryLock(delegationLockPath(projectRoot), async () => {
         const filePath = delegationLogPath(projectRoot);
         const prior = await readDelegationLedger(projectRoot);
@@ -802,6 +958,7 @@ export async function appendDelegation(projectRoot, entry) {
         if (prior.entries.some((existing) => existing.spanId === stamped.spanId && existing.status === stamped.status)) {
             return;
         }
+        assertSliceClaimInvariant(flowState, stamped, prior.entries);
         validateMonotonicTimestamps(stamped, prior.entries);
         if (stamped.status === "scheduled") {
             // v6.10.0 (P1+P2): for slice-implementer rows with declared
@@ -839,6 +996,39 @@ export async function appendDelegation(projectRoot, entry) {
         await writeSubagentTracker(projectRoot, ledger.entries);
     });
 }
+/**
+ * Scan delegation events for expired `leasedUntil` timestamps and append
+ * best-effort `cclaw_slice_lease_expired` audit rows (one per span/slice key).
+ */
+export async function reclaimExpiredDelegationClaims(projectRoot, now = new Date()) {
+    const { events } = await readDelegationEvents(projectRoot);
+    const seen = new Set();
+    let count = 0;
+    const ts = now.toISOString();
+    const filePath = delegationEventsPath(projectRoot);
+    const cutoff = Date.parse(ts);
+    for (const e of events) {
+        if (e.leaseState !== "claimed")
+            continue;
+        if (typeof e.leasedUntil !== "string" || e.leasedUntil.length === 0)
+            continue;
+        if (Date.parse(e.leasedUntil) > cutoff)
+            continue;
+        const key = `${e.spanId ?? ""}|${e.sliceId ?? ""}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        await fs.appendFile(filePath, `${JSON.stringify({
+            event: "cclaw_slice_lease_expired",
+            spanId: e.spanId,
+            sliceId: e.sliceId,
+            leasedUntil: e.leasedUntil,
+            eventTs: ts
+        })}\n`, { encoding: "utf8", mode: 0o600 });
+        count += 1;
+    }
+    return count;
+}
 /**
  * Aggregate the fulfillment mode cclaw expects for the active harness set.
  * Priority native > generic-dispatch > role-switch > waiver — the best

package/dist/flow-state.d.ts

@@ -121,7 +121,42 @@ export interface FlowState {
     completedStageMeta?: Partial<Record<FlowStage, {
         completedAt: string;
     }>>;
+    /**
+     * v6.12.0 — TDD migration cutover marker. When `cclaw-cli sync` detects an
+     * existing `06-tdd.md` with legacy per-slice tables but no auto-render
+     * markers, it inserts the markers and records the highest legacy slice id
+     * here (e.g. `"S-10"`). The TDD linter uses this value to:
+     *   - exempt slices `<= cutoverSliceId` from new mandatory rules (legacy
+     *     slices keep their markdown tables);
+     *   - emit `tdd_legacy_section_writes_after_cutover` advisory when a slice
+     *     id `> cutoverSliceId` appears in legacy per-slice sections of
+     *     `06-tdd.md` (post-cutover prose belongs in `tdd-slices/S-<id>.md`).
+     *
+     * Optional + best-effort: omitted on fresh installs and on legacy files
+     * sync hasn't visited yet.
+     */
+    tddCutoverSliceId?: string;
+    /**
+     * v6.13.0 — when `worktree-first` (default for newly initialized runs),
+     * slice-implementer work happens in isolated git worktrees with explicit
+     * claims/leases and deterministic fan-in integration.
+     *
+     * Omitted on legacy `flow-state.json` files: treated as `single-tree` via
+     * `effectiveWorktreeExecutionMode`.
+     */
+    worktreeExecutionMode?: "single-tree" | "worktree-first";
+    /**
+     * v6.13.0 — set by `cclaw-cli sync` when the plan predates parallel-metadata
+     * fields. Relaxes some plan linters for existing implementation units and
+     * defaults scheduler parallelism to opt-in only for those units.
+     */
+    legacyContinuation?: boolean;
 }
+/**
+ * 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";
 export interface StageInteractionHint {
     skipQuestions?: boolean;
     sourceStage?: FlowStage;

package/dist/flow-state.js

@@ -44,6 +44,13 @@ export function createInitialCloseoutState() {
         compoundPromoted: 0
     };
 }
+/**
+ * Effective worktree mode: legacy state files without the field keep
+ * single-tree scheduling to avoid breaking existing runs on upgrade.
+ */
+export function effectiveWorktreeExecutionMode(state) {
+    return state.worktreeExecutionMode ?? "single-tree";
+}
 export function isFlowTrack(value) {
     return typeof value === "string" && FLOW_TRACKS.includes(value);
 }

package/dist/gate-evidence.d.ts

@@ -66,6 +66,11 @@ export interface VerifyCurrentStageGateEvidenceOptions {
     extraStageFlags?: string[];
 }
 export declare function verifyCurrentStageGateEvidence(projectRoot: string, flowState: FlowState, options?: VerifyCurrentStageGateEvidenceOptions): Promise<GateEvidenceCheckResult>;
+/**
+ * Validates that every lane-backed slice which reached REFACTOR has a matching
+ * `cclaw_fanin_applied` audit row for the active run (v6.13.0 worktree-first).
+ */
+export declare function verifyTddWorktreeFanInClosure(projectRoot: string, flowState: FlowState): Promise<string[]>;
 export declare function verifyCompletedStagesGateClosure(flowState: FlowState): CompletedStagesClosureResult;
 export interface GateReconciliationResult {
     stage: FlowStage;

package/dist/gate-evidence.js

@@ -5,7 +5,8 @@ import { ELICITATION_STAGES, evaluateQaLogFloor } from "./artifact-linter/shared
 import { resolveArtifactPath } from "./artifact-paths.js";
 import { RUNTIME_ROOT } from "./constants.js";
 import { stageSchema } from "./content/stage-schema.js";
-import { readDelegationLedger } from "./delegation.js";
+import { readDelegationLedger, readDelegationEvents } from "./delegation.js";
+import { effectiveWorktreeExecutionMode } from "./flow-state.js";
 import { exists } from "./fs-utils.js";
 import { computeEarlyLoopStatus, isEarlyLoopStage, normalizeEarlyLoopMaxIterations } from "./early-loop.js";
 import { detectPublicApiChanges } from "./internal/detect-public-api-changes.js";
@@ -487,6 +488,62 @@ export async function verifyCurrentStageGateEvidence(projectRoot, flowState, opt
         qaLogFloor
     };
 }
+function sliceHasTerminalRefactor(events, runId, sliceId) {
+    for (const e of events) {
+        if (e.runId !== runId || e.stage !== "tdd" || e.sliceId !== sliceId)
+            continue;
+        if (e.agent !== "slice-implementer" || e.status !== "completed")
+            continue;
+        if (e.phase === "refactor" || e.phase === "refactor-deferred")
+            return true;
+    }
+    return false;
+}
+function closedSlicesWithLane(events, runId) {
+    const withLane = new Set();
+    for (const e of events) {
+        if (e.runId !== runId || e.stage !== "tdd")
+            continue;
+        if (e.agent !== "slice-implementer" || e.status !== "completed" || e.phase !== "green")
+            continue;
+        if (!e.ownerLaneId?.trim() || !e.sliceId)
+            continue;
+        withLane.add(e.sliceId);
+    }
+    const out = new Set();
+    for (const sid of withLane) {
+        if (sliceHasTerminalRefactor(events, runId, sid))
+            out.add(sid);
+    }
+    return out;
+}
+/**
+ * Validates that every lane-backed slice which reached REFACTOR has a matching
+ * `cclaw_fanin_applied` audit row for the active run (v6.13.0 worktree-first).
+ */
+export async function verifyTddWorktreeFanInClosure(projectRoot, flowState) {
+    if (effectiveWorktreeExecutionMode(flowState) !== "worktree-first")
+        return [];
+    const runId = flowState.activeRunId;
+    const { events, fanInAudits } = await readDelegationEvents(projectRoot);
+    const needing = closedSlicesWithLane(events, runId);
+    if (needing.size === 0)
+        return [];
+    const applied = new Set();
+    for (const a of fanInAudits) {
+        if (a.runId !== runId || a.event !== "cclaw_fanin_applied")
+            continue;
+        for (const s of a.sliceIds ?? [])
+            applied.add(s);
+    }
+    const issues = [];
+    for (const sid of needing) {
+        if (!applied.has(sid)) {
+            issues.push(`tdd worktree fan-in closure: slice ${sid} completed on a lane but cclaw_fanin_applied is missing for run ${runId}.`);
+        }
+    }
+    return issues;
+}
 export function verifyCompletedStagesGateClosure(flowState) {
     const issues = [];
     const openStages = [];

package/dist/install.js

@@ -33,7 +33,8 @@ import { HARNESS_ADAPTERS, harnessShimFileNames, harnessShimSkillNames, syncHarn
 import { validateHookDocument } from "./hook-schema.js";
 import { detectHarnesses } from "./init-detect.js";
 import { classifyCodexHooksFlag, codexConfigPath, readCodexConfig } from "./codex-feature-flag.js";
-import { CorruptFlowStateError, ensureRunSystem } from "./runs.js";
+import { CorruptFlowStateError, ensureRunSystem, readFlowState, writeFlowState } from "./runs.js";
+import { PLAN_SPLIT_DEFAULT_WAVE_SIZE, buildParallelExecutionPlanSection, planArtifactLacksV613ParallelMetadata, upsertParallelExecutionPlanSection } from "./internal/plan-split-waves.js";
 import { FLOW_STAGES } from "./types.js";
 const OPENCODE_PLUGIN_REL_PATH = ".opencode/plugins/cclaw-plugin.mjs";
 const CURSOR_RULE_REL_PATH = ".cursor/rules/cclaw-workflow.mdc";
@@ -835,6 +836,173 @@ async function writeState(projectRoot, config, forceReset = false) {
     const state = createInitialFlowState({ track: "standard" });
     await writeFileSafe(statePath, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
 }
+/**
+ * v6.12.0 — TDD auto-cutover sync. When sync detects a legacy `06-tdd.md`
+ * (no auto-render markers) carrying observable slice activity (e.g. `S-N`
+ * referenced ≥3 times in slice-section bodies), insert the v6.11.0 marker
+ * skeleton + a one-line cutover banner and stamp the highest legacy slice
+ * id into `flow-state.json::tddCutoverSliceId`. Idempotent: re-running sync
+ * is byte-stable once markers are present.
+ *
+ * Design notes:
+ *   - Best-effort: read failures, missing flow-state, or unparseable JSON
+ *     all short-circuit silently. We never throw inside sync for migration
+ *     bookkeeping.
+ *   - We use `writeFlowState({ allowReset: true })` so we don't trip
+ *     `validateFlowTransition` (the only field we mutate is the new
+ *     additive `tddCutoverSliceId`; transition rules don't apply).
+ *   - The banner mirrors the language in the `## Per-Slice Ritual`
+ *     skill section so a reader of `06-tdd.md` who hasn't seen v6.12.0
+ *     understands the contract change.
+ */
+async function applyTddCutoverIfNeeded(projectRoot) {
+    const tddArtifactPath = runtimePath(projectRoot, "artifacts", "06-tdd.md");
+    let existing;
+    try {
+        existing = await fs.readFile(tddArtifactPath, "utf8");
+    }
+    catch {
+        return;
+    }
+    if (existing.includes("<!-- auto-start: tdd-slice-summary -->")) {
+        return;
+    }
+    const sliceMatches = [...existing.matchAll(/\bS-(\d+)\b/gu)];
+    if (sliceMatches.length < 3) {
+        return;
+    }
+    let maxSliceNum = 0;
+    for (const match of sliceMatches) {
+        const n = Number.parseInt(match[1], 10);
+        if (Number.isFinite(n) && n > maxSliceNum) {
+            maxSliceNum = n;
+        }
+    }
+    if (maxSliceNum <= 0) {
+        return;
+    }
+    const cutoverSliceId = `S-${maxSliceNum}`;
+    const banner = [
+        `<!-- v6.12.0 cutover: slices S-1..${cutoverSliceId} use legacy per-slice tables.`,
+        `     New slices (S-${maxSliceNum + 1}+) use phase events + tdd-slices/<id>.md.`,
+        "     Controller MUST NOT add new rows to legacy sections. -->"
+    ].join("\n");
+    const slicesIndexBlock = [
+        "<!-- auto-start: slices-index -->",
+        "## Slices Index",
+        "",
+        "_Auto-rendered from `tdd-slices/S-*.md` once slice-documenter or controller writes per-slice files. Do not edit by hand._",
+        "<!-- auto-end: slices-index -->"
+    ].join("\n");
+    const summaryBlock = [
+        "<!-- auto-start: tdd-slice-summary -->",
+        "<!-- auto-end: tdd-slice-summary -->"
+    ].join("\n");
+    let nextRaw;
+    if (existing.startsWith("---\n")) {
+        const fmEnd = existing.indexOf("\n---", 4);
+        if (fmEnd >= 0) {
+            const fmClose = fmEnd + 4;
+            const head = existing.slice(0, fmClose);
+            const tail = existing.slice(fmClose);
+            nextRaw = `${head}\n\n${banner}\n\n${slicesIndexBlock}\n\n${summaryBlock}\n${tail}`;
+        }
+        else {
+            nextRaw = `${banner}\n\n${slicesIndexBlock}\n\n${summaryBlock}\n\n${existing}`;
+        }
+    }
+    else {
+        nextRaw = `${banner}\n\n${slicesIndexBlock}\n\n${summaryBlock}\n\n${existing}`;
+    }
+    await writeFileSafe(tddArtifactPath, nextRaw);
+    const slicesDir = runtimePath(projectRoot, "artifacts", "tdd-slices");
+    await ensureDir(slicesDir);
+    const flowStatePath = runtimePath(projectRoot, "state", "flow-state.json");
+    let flowStateRaw;
+    try {
+        flowStateRaw = await fs.readFile(flowStatePath, "utf8");
+    }
+    catch {
+        return;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(flowStateRaw);
+    }
+    catch {
+        return;
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return;
+    }
+    const obj = parsed;
+    if (typeof obj.tddCutoverSliceId === "string" && obj.tddCutoverSliceId.length > 0) {
+        return;
+    }
+    obj.tddCutoverSliceId = cutoverSliceId;
+    await writeFileSafe(flowStatePath, `${JSON.stringify(obj, null, 2)}\n`, { mode: 0o600 });
+}
+const V613_LEGACY_PLAN_BANNER = "<!-- legacy-continuation: predates v6.13 parallel metadata. New units MAY add dependsOn/claimedPaths/parallelizable; existing units treated as best-effort serial. -->";
+/**
+ * v6.13.0 — when `05-plan.md` lacks parallel-metadata bullets on any
+ * implementation unit, stamp `flow-state.json::legacyContinuation`, insert
+ * a banner + managed Parallel Execution Plan stub, and keep behavior idempotent.
+ */
+async function applyPlanLegacyContinuationIfNeeded(projectRoot) {
+    const planArtifactPath = runtimePath(projectRoot, "artifacts", "05-plan.md");
+    let existingPlan;
+    try {
+        existingPlan = await fs.readFile(planArtifactPath, "utf8");
+    }
+    catch {
+        return;
+    }
+    if (!planArtifactLacksV613ParallelMetadata(existingPlan)) {
+        return;
+    }
+    let nextPlan = existingPlan;
+    if (!nextPlan.includes("legacy-continuation: predates v6.13")) {
+        if (nextPlan.startsWith("---\n")) {
+            const fmEnd = nextPlan.indexOf("\n---", 4);
+            if (fmEnd >= 0) {
+                const fmClose = fmEnd + 4;
+                const head = nextPlan.slice(0, fmClose);
+                const tail = nextPlan.slice(fmClose);
+                nextPlan = `${head}\n\n${V613_LEGACY_PLAN_BANNER}\n${tail}`;
+            }
+            else {
+                nextPlan = `${V613_LEGACY_PLAN_BANNER}\n\n${nextPlan}`;
+            }
+        }
+        else {
+            nextPlan = `${V613_LEGACY_PLAN_BANNER}\n\n${nextPlan}`;
+        }
+    }
+    const parallelStub = buildParallelExecutionPlanSection([], PLAN_SPLIT_DEFAULT_WAVE_SIZE);
+    if (!nextPlan.includes("<!-- parallel-exec-managed-start -->")) {
+        nextPlan = upsertParallelExecutionPlanSection(nextPlan, parallelStub);
+    }
+    if (nextPlan !== existingPlan) {
+        await writeFileSafe(planArtifactPath, nextPlan);
+    }
+    const flowStatePath = runtimePath(projectRoot, "state", "flow-state.json");
+    if (!(await exists(flowStatePath))) {
+        return;
+    }
+    try {
+        const state = await readFlowState(projectRoot);
+        if (state.legacyContinuation === true) {
+            return;
+        }
+        await writeFlowState(projectRoot, { ...state, legacyContinuation: true }, {
+            allowReset: true,
+            writerSubsystem: "plan-legacy-continuation-sync"
+        });
+    }
+    catch {
+        // Best-effort: corrupt/missing state is handled elsewhere on sync.
+    }
+}
 async function cleanLegacyArtifacts(projectRoot) {
     for (const legacyFolder of DEPRECATED_UTILITY_SKILL_FOLDERS) {
         await removeBestEffort(runtimePath(projectRoot, "skills", legacyFolder), true);
@@ -985,6 +1153,10 @@ async function materializeRuntime(projectRoot, config, forceStateReset, operatio
             writeRulebook(projectRoot)
         ]);
         await writeState(projectRoot, config, forceStateReset);
+        if (operation === "sync" || operation === "upgrade") {
+            await applyTddCutoverIfNeeded(projectRoot);
+            await applyPlanLegacyContinuationIfNeeded(projectRoot);
+        }
         try {
             await ensureRunSystem(projectRoot, { createIfMissing: false });
         }

package/dist/integration-fanin.d.ts

@@ -0,0 +1,44 @@
+import { type FlowState } from "./flow-state.js";
+import type { WorktreeLaneId } from "./worktree-types.js";
+export type FanInEventKind = "applied" | "conflict" | "resolved" | "abandoned";
+export interface FanInLaneOptions {
+    projectRoot: string;
+    /** Lane directory under `.cclaw/worktrees/<laneId>`. */
+    laneId: WorktreeLaneId;
+    /** Integration branch to receive the patch (must already exist locally). */
+    integrationBranch: string;
+    /**
+     * Baseline ref for `git diff` in the lane (fork point vs integration).
+     * When omitted, computed as `git merge-base <integration> HEAD` in the lane.
+     */
+    baseRef?: string;
+}
+export interface FanInLaneResult {
+    ok: boolean;
+    event: FanInEventKind;
+    details: string;
+}
+/**
+ * Build a unified diff from `baseRef..HEAD` in the lane worktree and apply it
+ * to the integration branch in the main repo using three-way merge.
+ * On conflict, the integration branch working tree is reset and, when possible,
+ * git HEAD is restored to the branch that was checked out before fan-in.
+ */
+export declare function fanInLane(options: FanInLaneOptions): Promise<FanInLaneResult>;
+export interface ResolverDispatchHint {
+    sliceId: string;
+    command: string;
+}
+/**
+ * Returns the canonical CLI hint for resolving fan-in conflicts for a slice.
+ */
+export declare function buildResolveConflictDispatchHint(sliceId: string): ResolverDispatchHint;
+/**
+ * Merge every lane that recorded a completed GREEN `ownerLaneId` for the
+ * active run, then emit `cclaw_fanin_*` audit rows. Does nothing in
+ * `single-tree` mode or when git is unavailable.
+ */
+export declare function runTddDeterministicFanInBeforeAdvance(projectRoot: string, flowState: FlowState): Promise<{
+    ok: boolean;
+    issues: string[];
+}>;