cclaw-cli 6.12.0 → 6.13.1

package/dist/integration-fanin.js

@@ -0,0 +1,180 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { exists } from "./fs-utils.js";
+import { readDelegationEvents, recordCclawFanInAudit } from "./delegation.js";
+import { effectiveWorktreeExecutionMode } from "./flow-state.js";
+const execFileAsync = promisify(execFile);
+const WORKTREES_SEG = ".cclaw/worktrees";
+/**
+ * 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 async function fanInLane(options) {
+    const { projectRoot, laneId, integrationBranch } = options;
+    const workdir = path.join(projectRoot, WORKTREES_SEG, laneId);
+    if (!(await exists(workdir))) {
+        return { ok: false, event: "abandoned", details: `missing lane workdir ${workdir}` };
+    }
+    let integrationRef;
+    try {
+        integrationRef = (await execFileAsync("git", ["rev-parse", "--verify", integrationBranch], {
+            cwd: projectRoot
+        })).stdout.trim();
+    }
+    catch {
+        return {
+            ok: false,
+            event: "abandoned",
+            details: `integration branch/ref not found: ${integrationBranch}`
+        };
+    }
+    let baseRef = options.baseRef?.trim() ?? "";
+    if (baseRef.length === 0) {
+        try {
+            baseRef = (await execFileAsync("git", ["merge-base", integrationRef, "HEAD"], { cwd: workdir })).stdout.trim();
+        }
+        catch (err) {
+            return {
+                ok: false,
+                event: "abandoned",
+                details: `cannot merge-base lane ${laneId} with ${integrationBranch}: ${err instanceof Error ? err.message : String(err)}`
+            };
+        }
+    }
+    const patchFile = path.join(projectRoot, WORKTREES_SEG, `.fanin-${laneId}.patch`);
+    let restoreBranch = null;
+    try {
+        let curBranch = "";
+        try {
+            curBranch = (await execFileAsync("git", ["rev-parse", "--abbrev-ref", "HEAD"], { cwd: projectRoot })).stdout.trim();
+        }
+        catch {
+            curBranch = "";
+        }
+        if (curBranch.length > 0 && curBranch !== integrationBranch && curBranch !== "HEAD") {
+            restoreBranch = curBranch;
+        }
+        const { stdout: diffOut } = await execFileAsync("git", ["diff", `${baseRef}..HEAD`], { cwd: workdir, maxBuffer: 64 * 1024 * 1024 });
+        if (diffOut.trim().length === 0) {
+            return { ok: true, event: "applied", details: "empty diff; nothing to merge" };
+        }
+        await fs.writeFile(patchFile, diffOut, "utf8");
+        await execFileAsync("git", ["checkout", integrationBranch], { cwd: projectRoot });
+        try {
+            await execFileAsync("git", ["apply", "--3way", patchFile], { cwd: projectRoot });
+            return { ok: true, event: "applied", details: `applied lane ${laneId} onto ${integrationBranch}` };
+        }
+        catch (err) {
+            await execFileAsync("git", ["checkout", "--", "."], { cwd: projectRoot }).catch(() => undefined);
+            if (restoreBranch) {
+                await execFileAsync("git", ["checkout", restoreBranch], { cwd: projectRoot }).catch(() => undefined);
+            }
+            const msg = err instanceof Error ? err.message : String(err);
+            return {
+                ok: false,
+                event: "conflict",
+                details: `git apply --3way reported conflicts for lane ${laneId}: ${msg}`
+            };
+        }
+    }
+    finally {
+        await fs.rm(patchFile, { force: true });
+    }
+}
+/**
+ * Returns the canonical CLI hint for resolving fan-in conflicts for a slice.
+ */
+export function buildResolveConflictDispatchHint(sliceId) {
+    return {
+        sliceId,
+        command: `slice-implementer --phase resolve-conflict --slice ${sliceId}`
+    };
+}
+/**
+ * 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 async function runTddDeterministicFanInBeforeAdvance(projectRoot, flowState) {
+    if (effectiveWorktreeExecutionMode(flowState) !== "worktree-first") {
+        return { ok: true, issues: [] };
+    }
+    let integrationBranch;
+    try {
+        integrationBranch = (await execFileAsync("git", ["rev-parse", "--abbrev-ref", "HEAD"], { cwd: projectRoot })).stdout.trim();
+    }
+    catch {
+        return {
+            ok: false,
+            issues: ["worktree fan-in: cannot read current git branch (not a repository or detached HEAD unsupported here)."]
+        };
+    }
+    const { events } = await readDelegationEvents(projectRoot);
+    const runId = flowState.activeRunId;
+    const laneToSlices = new Map();
+    for (const e of events) {
+        if (e.runId !== runId || e.stage !== "tdd")
+            continue;
+        if (e.agent !== "slice-implementer")
+            continue;
+        if (e.status !== "completed" || e.phase !== "green")
+            continue;
+        const lane = e.ownerLaneId?.trim();
+        const sid = e.sliceId?.trim();
+        if (!lane || !sid)
+            continue;
+        if (!laneToSlices.has(lane))
+            laneToSlices.set(lane, new Set());
+        laneToSlices.get(lane).add(sid);
+    }
+    if (laneToSlices.size === 0) {
+        return { ok: true, issues: [] };
+    }
+    const issues = [];
+    for (const [laneId, sliceSet] of laneToSlices) {
+        const result = await fanInLane({
+            projectRoot,
+            laneId: laneId,
+            integrationBranch,
+            baseRef: undefined
+        });
+        const sliceIds = [...sliceSet].sort();
+        if (!result.ok && result.event === "conflict") {
+            await recordCclawFanInAudit(projectRoot, {
+                kind: "cclaw_fanin_conflict",
+                runId,
+                laneId,
+                sliceIds,
+                integrationBranch,
+                details: result.details
+            });
+            issues.push(`${result.details} — ${buildResolveConflictDispatchHint(sliceIds[0] ?? "S-1").command}`);
+            continue;
+        }
+        if (!result.ok) {
+            await recordCclawFanInAudit(projectRoot, {
+                kind: "cclaw_fanin_abandoned",
+                runId,
+                laneId,
+                sliceIds,
+                integrationBranch,
+                details: result.details
+            });
+            issues.push(result.details);
+            continue;
+        }
+        await recordCclawFanInAudit(projectRoot, {
+            kind: "cclaw_fanin_applied",
+            runId,
+            laneId,
+            sliceIds,
+            integrationBranch,
+            details: result.details
+        });
+    }
+    return { ok: issues.length === 0, issues };
+}

package/dist/internal/advance-stage/advance.js

@@ -2,7 +2,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { resolveArtifactPath } from "../../artifact-paths.js";
 import { appendDelegation, checkMandatoryDelegations, readDelegationEvents, readDelegationLedger } from "../../delegation.js";
-import { verifyCompletedStagesGateClosure, verifyCurrentStageGateEvidence } from "../../gate-evidence.js";
+import { verifyCompletedStagesGateClosure, verifyCurrentStageGateEvidence, verifyTddWorktreeFanInClosure } from "../../gate-evidence.js";
 import { extractMarkdownSectionBody, learningsParseFailureHumanSummary, parseLearningsSection } from "../../artifact-linter.js";
 import { getAvailableTransitions, getTransitionGuards } from "../../flow-state.js";
 import { appendKnowledge } from "../../knowledge-store.js";
@@ -13,6 +13,7 @@ import { unique } from "./helpers.js";
 import { AUTO_REVIEW_LOOP_GATE_BY_STAGE, reviewLoopArtifactFixHint, reviewLoopEnvelopeExample, validateGateEvidenceShape } from "./review-loop.js";
 import { ensureProactiveDelegationTrace } from "./proactive-delegation-trace.js";
 import { consumeWaiverToken } from "../waiver-grant.js";
+import { runTddDeterministicFanInBeforeAdvance } from "../../integration-fanin.js";
 function resolveSuccessorTransition(stage, track, transitionTargets, satisfiedGuards, selectedTransitionGuards) {
     const natural = transitionTargets[0] ?? null;
     const specialTargets = transitionTargets.filter((target) => target !== natural);
@@ -602,6 +603,20 @@ export async function runAdvanceStage(projectRoot, args, io) {
     }
     const satisfiedGuards = new Set([...nextPassed, ...selectedTransitionGuards]);
     const successor = resolveSuccessorTransition(args.stage, flowState.track, transitionTargets, satisfiedGuards, new Set(selectedTransitionGuards));
+    if (args.stage === "tdd" && successor !== null && successor !== "tdd") {
+        const fanIn = await runTddDeterministicFanInBeforeAdvance(projectRoot, flowState);
+        if (!fanIn.ok) {
+            io.stderr.write(`cclaw internal advance-stage: deterministic worktree fan-in failed:\n${fanIn.issues
+                .map((line) => `  - ${line}`)
+                .join("\n")}\n`);
+            return 1;
+        }
+        const closure = await verifyTddWorktreeFanInClosure(projectRoot, flowState);
+        if (closure.length > 0) {
+            io.stderr.write(`cclaw internal advance-stage: ${closure.join(" | ")}\n`);
+            return 1;
+        }
+    }
     const completedStages = blockedReviewRoute
         ? flowState.completedStages.filter((finished) => finished !== args.stage)
         : flowState.completedStages.includes(args.stage)

package/dist/internal/advance-stage/start-flow.js

@@ -175,7 +175,8 @@ export async function runStartFlow(projectRoot, args, io) {
             guardEvidence,
             stageGateCatalog,
             rewinds: current.rewinds,
-            staleStages: current.staleStages
+            staleStages: current.staleStages,
+            worktreeExecutionMode: current.worktreeExecutionMode ?? "worktree-first"
         };
         const validation = await buildValidationReport(projectRoot, nextState);
         const evidenceIssues = completedStageClosureEvidenceIssues(nextState);
@@ -193,6 +194,7 @@ export async function runStartFlow(projectRoot, args, io) {
         if (nextTaskClass !== undefined) {
             nextState = { ...nextState, taskClass: nextTaskClass };
         }
+        nextState = { ...nextState, worktreeExecutionMode: "worktree-first" };
     }
     if (args.fromIdeaArtifact) {
         const existingHints = nextState.interactionHints ?? {};

package/dist/internal/advance-stage.js

@@ -14,8 +14,9 @@ import { parseAdvanceStageArgs, parseCancelRunArgs, parseHookArgs, parseRewindAr
 import { parseFlowStateRepairArgs, runFlowStateRepair } from "./flow-state-repair.js";
 import { parseWaiverGrantArgs, runWaiverGrant } from "./waiver-grant.js";
 import { FlowStateGuardMismatchError, verifyFlowStateGuard } from "../run-persistence.js";
-import { DelegationTimestampError, DispatchCapError, DispatchDuplicateError, DispatchOverlapError } from "../delegation.js";
+import { DelegationTimestampError, DispatchCapError, DispatchClaimInvalidError, DispatchDuplicateError, DispatchOverlapError } from "../delegation.js";
 import { parsePlanSplitWavesArgs, runPlanSplitWaves } from "./plan-split-waves.js";
+import { runSetWorktreeMode } from "./set-worktree-mode.js";
 /**
  * Subcommands that mutate or consult flow-state.json via the CLI runtime.
  * They all require the sha256 sidecar to match before continuing so a
@@ -28,12 +29,13 @@ const GUARD_ENFORCED_SUBCOMMANDS = new Set([
     "cancel-run",
     "rewind",
     "verify-flow-state-diff",
-    "verify-current-state"
+    "verify-current-state",
+    "set-worktree-mode"
 ]);
 export async function runInternalCommand(projectRoot, argv, io) {
     const [subcommand, ...tokens] = argv;
     if (!subcommand) {
-        io.stderr.write("cclaw internal requires a subcommand: advance-stage | start-flow | cancel-run | rewind | verify-flow-state-diff | verify-current-state | envelope-validate | tdd-red-evidence | tdd-loop-status | early-loop-status | compound-readiness | runtime-integrity | hook | flow-state-repair | waiver-grant | plan-split-waves\n");
+        io.stderr.write("cclaw internal requires a subcommand: advance-stage | start-flow | cancel-run | rewind | verify-flow-state-diff | verify-current-state | envelope-validate | tdd-red-evidence | tdd-loop-status | early-loop-status | compound-readiness | runtime-integrity | hook | flow-state-repair | waiver-grant | plan-split-waves | set-worktree-mode\n");
         return 1;
     }
     try {
@@ -88,7 +90,10 @@ export async function runInternalCommand(projectRoot, argv, io) {
         if (subcommand === "plan-split-waves") {
             return await runPlanSplitWaves(projectRoot, parsePlanSplitWavesArgs(tokens), io);
         }
-        io.stderr.write(`Unknown internal subcommand: ${subcommand}. Expected advance-stage | start-flow | cancel-run | rewind | verify-flow-state-diff | verify-current-state | envelope-validate | tdd-red-evidence | tdd-loop-status | early-loop-status | compound-readiness | runtime-integrity | hook | flow-state-repair | waiver-grant | plan-split-waves\n`);
+        if (subcommand === "set-worktree-mode") {
+            return await runSetWorktreeMode(projectRoot, tokens, io);
+        }
+        io.stderr.write(`Unknown internal subcommand: ${subcommand}. Expected advance-stage | start-flow | cancel-run | rewind | verify-flow-state-diff | verify-current-state | envelope-validate | tdd-red-evidence | tdd-loop-status | early-loop-status | compound-readiness | runtime-integrity | hook | flow-state-repair | waiver-grant | plan-split-waves | set-worktree-mode\n`);
         return 1;
     }
     catch (err) {
@@ -112,6 +117,10 @@ export async function runInternalCommand(projectRoot, argv, io) {
             io.stderr.write(`error: dispatch_cap — ${err.message}\n`);
             return 2;
         }
+        if (err instanceof DispatchClaimInvalidError) {
+            io.stderr.write(`error: dispatch_claim_invalid — ${err.message}\n`);
+            return 2;
+        }
         io.stderr.write(`cclaw internal ${subcommand} failed: ${err instanceof Error ? err.message : String(err)}\n`);
         return 1;
     }

package/dist/internal/plan-split-waves.d.ts

@@ -29,8 +29,54 @@ export interface PlanSplitWavesArgs {
     force: boolean;
     json: boolean;
 }
-export declare const PLAN_SPLIT_DEFAULT_WAVE_SIZE = 25;
+export declare const PLAN_SPLIT_DEFAULT_WAVE_SIZE = 5;
 export declare const PLAN_SPLIT_SMALL_PLAN_THRESHOLD = 50;
+/** v6.13.1 — member line in Parallel Execution Plan or wave-NN.md */
+export interface ParsedParallelWaveMember {
+    sliceId: string;
+    unitId: string;
+}
+export interface ParsedParallelWave {
+    waveId: string;
+    members: ParsedParallelWaveMember[];
+}
+export declare class WavePlanDuplicateSliceError extends Error {
+    constructor(message: string);
+}
+export declare class WavePlanMergeConflictError extends Error {
+    constructor(message: string);
+}
+/**
+ * Raw body between parallel execution managed markers (no markers included).
+ */
+export declare function extractParallelExecutionManagedBody(planMarkdown: string): string | null;
+/**
+ * Members list after `Members:` in Parallel Execution Plan / wave-NN headers.
+ * Supports markdown bold `**Members:**` (colon between Members and closing `**`)
+ * and plain `Members:`.
+ */
+export declare function extractMembersListFromLine(trimmedLine: string): string | null;
+/**
+ * Parse `## Parallel Execution Plan` managed block for wave headings and Members lines.
+ * Malformed member tokens are skipped. Duplicate slice ids in one plan source throw.
+ */
+export declare function parseParallelExecutionPlanWaves(planMarkdown: string): ParsedParallelWave[];
+/**
+ * Parse a single wave-NN.md: prefer a `Members:` line in the header; otherwise
+ * collect distinct S-N tokens in the first lines (legacy).
+ */
+export declare function parseWavePlanFileBody(body: string, waveId: string): ParsedParallelWave;
+export declare function parseWavePlanDirectory(artifactsDir: string): Promise<ParsedParallelWave[]>;
+/**
+ * Merge wave definitions: managed Parallel Execution Plan first, then wave-NN.md.
+ * Same slice must map to the same wave id and unit id in both sources or a
+ * `WavePlanMergeConflictError` is thrown.
+ */
+export declare function mergeParallelWaveDefinitions(primary: ParsedParallelWave[], secondary: ParsedParallelWave[]): ParsedParallelWave[];
+/**
+ * One-line operator hint after sync when a multi-member wave exists.
+ */
+export declare function formatNextParallelWaveSyncHint(merged: ParsedParallelWave[]): string | null;
 export interface ParsedImplementationUnit {
     id: string;
     /**
@@ -42,6 +88,44 @@ export interface ParsedImplementationUnit {
     /** Repo-relative path declarations from the optional `Files:` line. */
     paths: string[];
 }
+export interface ImplementationUnitParallelFields {
+    unitId: string;
+    dependsOn: string[];
+    claimedPaths: string[];
+    parallelizable: boolean;
+    riskTier: "low" | "standard" | "high";
+    lane?: string;
+}
+export interface ParseImplementationUnitParallelOptions {
+    /**
+     * Legacy continuation (v6.13.0): when the plan predates explicit parallel
+     * bullets, units without a `parallelizable:` line default to serial eligibility
+     * in the scheduler (`parallelizable: false`).
+     */
+    legacyParallelDefaultSerial?: boolean;
+}
+/**
+ * Parse v6.13 parallel-metadata bullets from an implementation unit body.
+ * Missing keys use conservative defaults (`dependsOn: []`, `parallelizable: true`
+ * unless `legacyParallelDefaultSerial` is set).
+ */
+export declare function parseImplementationUnitParallelFields(unit: ParsedImplementationUnit, options?: ParseImplementationUnitParallelOptions): ImplementationUnitParallelFields;
+/**
+ * True when the plan has implementation units but any unit is missing v6.13.0
+ * `dependsOn` / `claimedPaths` / `parallelizable` / `riskTier` bullets.
+ */
+export declare function planArtifactLacksV613ParallelMetadata(planMarkdown: string): boolean;
+export declare function compareCanonicalUnitIds(a: string, b: string): number;
+/**
+ * Group implementation units into waves: topological order, then greedy
+ * placement with disjoint `claimedPaths` and `cap` members per wave.
+ */
+export declare function buildConflictAwareWavesFromUnits(units: ParsedImplementationUnit[], cap: number): ParsedImplementationUnit[][];
+export declare function buildParallelExecutionPlanSection(waves: ParsedImplementationUnit[][], cap: number): string;
+/**
+ * Replace or append the managed Parallel Execution Plan block.
+ */
+export declare function upsertParallelExecutionPlanSection(planMarkdown: string, managedBlock: string): string;
 /**
  * Parse `## Implementation Units` section into individual unit blocks.
  * Recognizes the canonical heading shape in the TDD-velocity plan template