cclaw-cli 6.13.0 → 6.14.0

package/dist/delegation.js

@@ -9,7 +9,7 @@ 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";
+import { compareCanonicalUnitIds, mergeParallelWaveDefinitions, parseImplementationUnitParallelFields, parseImplementationUnits, parseParallelExecutionPlanWaves, parseWavePlanDirectory } 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 = [
@@ -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))
@@ -730,6 +746,158 @@ export function selectReadySlices(units, opts) {
     }
     return selected;
 }
+/**
+ * v6.13.1 — build scheduler rows from merged parallel wave definitions + plan units.
+ */
+export function readySliceUnitsFromMergedWaves(mergedWaves, planMarkdown, options) {
+    const units = parseImplementationUnits(planMarkdown);
+    const metaByUnit = new Map(units.map((u) => {
+        const m = parseImplementationUnitParallelFields(u, options);
+        return [m.unitId, m];
+    }));
+    const sliceSet = new Set();
+    for (const w of mergedWaves) {
+        for (const m of w.members) {
+            sliceSet.add(m.sliceId);
+        }
+    }
+    const out = [];
+    for (const sliceId of [...sliceSet].sort((a, b) => a.localeCompare(b))) {
+        const member = mergedWaves.flatMap((w) => w.members).find((x) => x.sliceId === sliceId);
+        if (!member)
+            continue;
+        const meta = metaByUnit.get(member.unitId);
+        if (!meta) {
+            out.push({
+                unitId: member.unitId,
+                sliceId,
+                dependsOn: [],
+                claimedPaths: [],
+                parallelizable: true
+            });
+            continue;
+        }
+        out.push({
+            unitId: meta.unitId,
+            sliceId,
+            dependsOn: meta.dependsOn,
+            claimedPaths: meta.claimedPaths,
+            parallelizable: meta.parallelizable
+        });
+    }
+    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[]`.
+ */
+export async function loadTddReadySlicePool(planMarkdown, artifactsDir, options) {
+    const merged = mergeParallelWaveDefinitions(parseParallelExecutionPlanWaves(planMarkdown), await parseWavePlanDirectory(artifactsDir));
+    return readySliceUnitsFromMergedWaves(merged, planMarkdown, options);
+}
 function readMaxParallelOverrideFromEnv() {
     const raw = process.env.CCLAW_MAX_PARALLEL_SLICE_IMPLEMENTERS;
     if (typeof raw !== "string" || raw.trim().length === 0)

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);
 }

package/dist/install.js

@@ -25,7 +25,7 @@ import { LANGUAGE_RULE_PACK_DIR, LEGACY_LANGUAGE_RULE_PACK_FOLDERS } from "./con
 import { RESEARCH_PLAYBOOKS } from "./content/research-playbooks.js";
 import { SUBAGENT_CONTEXT_SKILLS } from "./content/subagent-context-skills.js";
 import { CCLAW_AGENTS } from "./content/core-agents.js";
-import { createInitialFlowState } from "./flow-state.js";
+import { createInitialFlowState, effectiveWorktreeExecutionMode } from "./flow-state.js";
 import { ensureDir, exists, writeFileSafe } from "./fs-utils.js";
 import { ManagedResourceSession, setActiveManagedResourceSession } from "./managed-resources.js";
 import { ensureGitignore, removeGitignorePatterns } from "./gitignore.js";
@@ -34,7 +34,7 @@ import { validateHookDocument } from "./hook-schema.js";
 import { detectHarnesses } from "./init-detect.js";
 import { classifyCodexHooksFlag, codexConfigPath, readCodexConfig } from "./codex-feature-flag.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 { PLAN_SPLIT_DEFAULT_WAVE_SIZE, buildParallelExecutionPlanSection, formatNextParallelWaveSyncHint, mergeParallelWaveDefinitions, parseParallelExecutionPlanWaves, parseWavePlanDirectory, 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";
@@ -1003,6 +1003,90 @@ async function applyPlanLegacyContinuationIfNeeded(projectRoot) {
         // Best-effort: corrupt/missing state is handled elsewhere on sync.
     }
 }
+/**
+ * v6.14.0 — set stream-style defaults on `cclaw-cli sync` and print a
+ * one-line hint when defaults change. Strategy:
+ *
+ * - When `legacyContinuation: true` and `tddCheckpointMode` is unset, force
+ *   `tddCheckpointMode: "global-red"` (preserves hox wave protocol).
+ * - When `legacyContinuation: true` and `integrationOverseerMode` is unset,
+ *   force `integrationOverseerMode: "always"` (preserves v6.13 behavior).
+ * - When `legacyContinuation` is NOT true (new / standard projects) and
+ *   neither field is set, default to `tddCheckpointMode: "per-slice"`,
+ *   `integrationOverseerMode: "conditional"`. Also default
+ *   `worktreeExecutionMode: "worktree-first"` if unset.
+ *
+ * Returns a one-line hint string (or `null` if nothing changed) so callers
+ * can print it through the standard sync hint surface.
+ */
+async function applyV614DefaultsIfNeeded(projectRoot) {
+    // Defensive read — match `applyTddCutoverIfNeeded`'s pattern (raw +
+    // JSON.parse) so corrupt state is left untouched for the downstream
+    // fail-fast check in `materializeRuntime` (which expects to see the
+    // CorruptFlowStateError surfaced via `ensureRunSystem`). Calling
+    // `readFlowState` directly would quarantine the corrupt file and hide
+    // the failure from the caller.
+    const flowStatePath = runtimePath(projectRoot, "state", "flow-state.json");
+    let flowStateRaw;
+    try {
+        flowStateRaw = await fs.readFile(flowStatePath, "utf8");
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(flowStateRaw);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return null;
+    }
+    const obj = parsed;
+    const updates = {};
+    const summary = [];
+    const tddCheckpointModeSet = obj.tddCheckpointMode === "per-slice" || obj.tddCheckpointMode === "global-red";
+    const integrationOverseerModeSet = obj.integrationOverseerMode === "conditional" || obj.integrationOverseerMode === "always";
+    const worktreeExecutionModeSet = obj.worktreeExecutionMode === "worktree-first" || obj.worktreeExecutionMode === "single-tree";
+    const legacyContinuation = obj.legacyContinuation === true;
+    if (legacyContinuation) {
+        if (!tddCheckpointModeSet) {
+            updates.tddCheckpointMode = "global-red";
+            summary.push("tddCheckpointMode=global-red (legacyContinuation)");
+        }
+        if (!integrationOverseerModeSet) {
+            updates.integrationOverseerMode = "always";
+            summary.push("integrationOverseerMode=always (legacyContinuation)");
+        }
+    }
+    else {
+        if (!tddCheckpointModeSet) {
+            updates.tddCheckpointMode = "per-slice";
+            summary.push("tddCheckpointMode=per-slice");
+        }
+        if (!integrationOverseerModeSet) {
+            updates.integrationOverseerMode = "conditional";
+            summary.push("integrationOverseerMode=conditional");
+        }
+        if (!worktreeExecutionModeSet) {
+            updates.worktreeExecutionMode = "worktree-first";
+            summary.push("worktreeExecutionMode=worktree-first");
+        }
+    }
+    if (summary.length === 0) {
+        return null;
+    }
+    const merged = { ...obj, ...updates };
+    try {
+        await writeFileSafe(flowStatePath, `${JSON.stringify(merged, null, 2)}\n`, { mode: 0o600 });
+    }
+    catch {
+        return null;
+    }
+    return `v6.14.0 stream-style defaults applied: ${summary.join(", ")}. To opt out, edit .cclaw/state/flow-state.json directly or pin the legacy mode (tddCheckpointMode="global-red", integrationOverseerMode="always").`;
+}
 async function cleanLegacyArtifacts(projectRoot) {
     for (const legacyFolder of DEPRECATED_UTILITY_SKILL_FOLDERS) {
         await removeBestEffort(runtimePath(projectRoot, "skills", legacyFolder), true);
@@ -1135,6 +1219,28 @@ async function assertExpectedHarnessShims(projectRoot, harnesses) {
         }
     }
 }
+async function maybeLogParallelWaveDispatchHint(projectRoot) {
+    const flowPath = runtimePath(projectRoot, "state", "flow-state.json");
+    if (!(await exists(flowPath)))
+        return;
+    try {
+        const state = await readFlowState(projectRoot);
+        if (effectiveWorktreeExecutionMode(state) !== "worktree-first")
+            return;
+        const planPath = runtimePath(projectRoot, "artifacts", "05-plan.md");
+        if (!(await exists(planPath)))
+            return;
+        const planRaw = await fs.readFile(planPath, "utf8");
+        const merged = mergeParallelWaveDefinitions(parseParallelExecutionPlanWaves(planRaw), await parseWavePlanDirectory(runtimePath(projectRoot, "artifacts")));
+        const hint = formatNextParallelWaveSyncHint(merged);
+        if (hint) {
+            process.stdout.write(`cclaw: ${hint}\n`);
+        }
+    }
+    catch {
+        // best-effort note only
+    }
+}
 async function materializeRuntime(projectRoot, config, forceStateReset, operation = "sync") {
     await warnStaleInitSentinel(projectRoot, operation);
     const sentinelPath = await writeInitSentinel(projectRoot, operation);
@@ -1156,6 +1262,10 @@ async function materializeRuntime(projectRoot, config, forceStateReset, operatio
         if (operation === "sync" || operation === "upgrade") {
             await applyTddCutoverIfNeeded(projectRoot);
             await applyPlanLegacyContinuationIfNeeded(projectRoot);
+            const v614Hint = await applyV614DefaultsIfNeeded(projectRoot);
+            if (v614Hint) {
+                process.stdout.write(`cclaw: ${v614Hint}\n`);
+            }
         }
         try {
             await ensureRunSystem(projectRoot, { createIfMissing: false });
@@ -1175,6 +1285,9 @@ async function materializeRuntime(projectRoot, config, forceStateReset, operatio
         await assertExpectedHarnessShims(projectRoot, harnesses);
         await writeCursorWorkflowRule(projectRoot, harnesses);
         await ensureGitignore(projectRoot);
+        if (operation === "sync" || operation === "upgrade") {
+            await maybeLogParallelWaveDispatchHint(projectRoot);
+        }
         await managedSession.commit();
         await fs.unlink(sentinelPath).catch(() => undefined);
     }

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

@@ -31,6 +31,52 @@ export interface PlanSplitWavesArgs {
 }
 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;
     /**