cclaw-cli 6.9.0 → 6.10.0

package/dist/internal/advance-stage.js

@@ -14,7 +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, DispatchDuplicateError } from "../delegation.js";
+import { DelegationTimestampError, DispatchCapError, DispatchDuplicateError, DispatchOverlapError } from "../delegation.js";
+import { parseTddSliceRecordArgs, runTddSliceRecord } from "../tdd-slices.js";
+import { parsePlanSplitWavesArgs, runPlanSplitWaves } from "./plan-split-waves.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
@@ -32,7 +34,7 @@ const GUARD_ENFORCED_SUBCOMMANDS = new Set([
 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\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 | tdd-slice-record | early-loop-status | compound-readiness | runtime-integrity | hook | flow-state-repair | waiver-grant | plan-split-waves\n");
         return 1;
     }
     try {
@@ -84,7 +86,13 @@ export async function runInternalCommand(projectRoot, argv, io) {
         if (subcommand === "waiver-grant") {
             return await runWaiverGrant(projectRoot, parseWaiverGrantArgs(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\n`);
+        if (subcommand === "tdd-slice-record") {
+            return await runTddSliceRecord(projectRoot, parseTddSliceRecordArgs(tokens), 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 | tdd-slice-record | early-loop-status | compound-readiness | runtime-integrity | hook | flow-state-repair | waiver-grant | plan-split-waves\n`);
         return 1;
     }
     catch (err) {
@@ -100,6 +108,14 @@ export async function runInternalCommand(projectRoot, argv, io) {
             io.stderr.write(`error: dispatch_duplicate — ${err.message}\n`);
             return 2;
         }
+        if (err instanceof DispatchOverlapError) {
+            io.stderr.write(`error: dispatch_overlap — ${err.message}\n`);
+            return 2;
+        }
+        if (err instanceof DispatchCapError) {
+            io.stderr.write(`error: dispatch_cap — ${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

@@ -0,0 +1,66 @@
+import type { Writable } from "node:stream";
+interface InternalIo {
+    stdout: Writable;
+    stderr: Writable;
+}
+/**
+ * v6.10.0 (P3) — split a large `05-plan.md` Implementation Units section
+ * into wave-NN.md sub-files so an executor can carry one wave at a time
+ * without re-reading the whole plan.
+ *
+ * Threshold contract:
+ *   - total units < SMALL_PLAN_THRESHOLD → no-op, exit 0.
+ *   - total units >= SMALL_PLAN_THRESHOLD → split into waves of `--wave-size`
+ *     (default 25).
+ *
+ * Files written:
+ *   - `<artifacts-dir>/wave-plans/wave-NN.md` per wave (1-indexed).
+ *   - In-place update to `05-plan.md` adding (or refreshing) a
+ *     `## Wave Plans` section between
+ *     `<!-- wave-split-managed-start -->` and `<!-- wave-split-managed-end -->`
+ *     markers. Outside-marker content is preserved verbatim.
+ *
+ * `--dry-run` prints the plan but does not write. `--force` overwrites
+ * existing wave files; without it, the command refuses to clobber.
+ */
+export interface PlanSplitWavesArgs {
+    waveSize: number;
+    dryRun: boolean;
+    force: boolean;
+    json: boolean;
+}
+export declare const PLAN_SPLIT_DEFAULT_WAVE_SIZE = 25;
+export declare const PLAN_SPLIT_SMALL_PLAN_THRESHOLD = 50;
+export interface ParsedImplementationUnit {
+    id: string;
+    /**
+     * The full markdown body of this unit, starting at the
+     * `### Implementation Unit U-N` heading and ending right before the
+     * next unit heading (or the next `## ` H2, or end of file).
+     */
+    body: string;
+    /** Repo-relative path declarations from the optional `Files:` line. */
+    paths: string[];
+}
+/**
+ * Parse `## Implementation Units` section into individual unit blocks.
+ * Recognizes the canonical heading shape in the TDD-velocity plan template
+ * (`### Implementation Unit U-<n>`). Tolerant of `Files:` listed either
+ * inline or as a `- **Files (...):**` bullet block.
+ */
+export declare function parseImplementationUnits(planMarkdown: string): ParsedImplementationUnit[];
+/**
+ * Pull repo-relative paths from a `Files:` line or the `Files (...)` bullet
+ * block. Both shapes appear in the wild; the parser extracts after the colon
+ * and splits on commas. Empty/whitespace items are dropped.
+ */
+export declare function extractPathsLine(unitBody: string): string[];
+export declare function parsePlanSplitWavesArgs(tokens: string[]): PlanSplitWavesArgs;
+/**
+ * Replace any existing managed Wave Plans block with the new one, or append
+ * it at the end of the file when no markers are present yet. The helper
+ * never touches text outside the markers.
+ */
+export declare function upsertWavePlansSection(planMarkdown: string, managedBlock: string): string;
+export declare function runPlanSplitWaves(projectRoot: string, args: PlanSplitWavesArgs, io: InternalIo): Promise<number>;
+export {};

package/dist/internal/plan-split-waves.js

@@ -0,0 +1,249 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { resolveArtifactPath } from "../artifact-paths.js";
+import { exists, writeFileSafe } from "../fs-utils.js";
+import { readFlowState } from "../runs.js";
+export const PLAN_SPLIT_DEFAULT_WAVE_SIZE = 25;
+export const PLAN_SPLIT_SMALL_PLAN_THRESHOLD = 50;
+const WAVE_PLANS_DIR = "wave-plans";
+const WAVE_MANAGED_START = "<!-- wave-split-managed-start -->";
+const WAVE_MANAGED_END = "<!-- wave-split-managed-end -->";
+/**
+ * Parse `## Implementation Units` section into individual unit blocks.
+ * Recognizes the canonical heading shape in the TDD-velocity plan template
+ * (`### Implementation Unit U-<n>`). Tolerant of `Files:` listed either
+ * inline or as a `- **Files (...):**` bullet block.
+ */
+export function parseImplementationUnits(planMarkdown) {
+    const units = [];
+    const headingRegex = /(^|\n)###\s+Implementation Unit\s+(U-\d+)\b/gu;
+    const matches = [];
+    let match;
+    while ((match = headingRegex.exec(planMarkdown)) !== null) {
+        const offset = match[1] === "" ? 0 : 1; // strip the leading newline if present
+        matches.push({
+            id: match[2],
+            start: match.index + offset,
+            headingEnd: match.index + match[0].length
+        });
+    }
+    for (let i = 0; i < matches.length; i += 1) {
+        const current = matches[i];
+        const next = matches[i + 1];
+        let endIndex = next ? next.start : planMarkdown.length;
+        // If a higher-level H2 (`## ...`) appears before the next unit, end at the H2.
+        const tail = planMarkdown.slice(current.headingEnd, endIndex);
+        const sectionBreak = /\n##\s+\S/u.exec(tail);
+        if (sectionBreak) {
+            endIndex = current.headingEnd + sectionBreak.index + 1; // include the trailing newline
+        }
+        const body = planMarkdown.slice(current.start, endIndex).replace(/\s+$/u, "");
+        units.push({
+            id: current.id,
+            body,
+            paths: extractPathsLine(body)
+        });
+    }
+    return units;
+}
+/**
+ * Pull repo-relative paths from a `Files:` line or the `Files (...)` bullet
+ * block. Both shapes appear in the wild; the parser extracts after the colon
+ * and splits on commas. Empty/whitespace items are dropped.
+ */
+export function extractPathsLine(unitBody) {
+    const lines = unitBody.split(/\r?\n/u);
+    for (const rawLine of lines) {
+        const line = rawLine.trim();
+        const filesMatch = /^[-*]?\s*\*?\*?Files\s*(?:\([^)]*\))?\s*:\*?\*?\s*(.*)$/iu.exec(line);
+        if (!filesMatch)
+            continue;
+        const remainder = filesMatch[1].trim();
+        if (remainder.length === 0)
+            continue;
+        return remainder
+            .split(",")
+            .map((item) => item.replace(/[`*]/gu, "").trim())
+            .filter((item) => item.length > 0);
+    }
+    return [];
+}
+export function parsePlanSplitWavesArgs(tokens) {
+    let waveSize = PLAN_SPLIT_DEFAULT_WAVE_SIZE;
+    let dryRun = false;
+    let force = false;
+    let json = false;
+    for (let i = 0; i < tokens.length; i += 1) {
+        const token = tokens[i];
+        const next = tokens[i + 1];
+        if (token === "--dry-run") {
+            dryRun = true;
+            continue;
+        }
+        if (token === "--force") {
+            force = true;
+            continue;
+        }
+        if (token === "--json") {
+            json = true;
+            continue;
+        }
+        if (token === "--wave-size" || token.startsWith("--wave-size=")) {
+            let raw = "";
+            if (token.startsWith("--wave-size=")) {
+                raw = token.slice("--wave-size=".length);
+            }
+            else {
+                if (next === undefined || next.startsWith("--")) {
+                    throw new Error("--wave-size requires an integer value.");
+                }
+                raw = next;
+                i += 1;
+            }
+            const trimmed = raw.trim();
+            if (!/^[0-9]+$/u.test(trimmed)) {
+                throw new Error("--wave-size must be a positive integer.");
+            }
+            waveSize = Number(trimmed);
+            if (waveSize < 1) {
+                throw new Error("--wave-size must be >= 1.");
+            }
+            continue;
+        }
+        throw new Error(`Unknown flag for internal plan-split-waves: ${token}`);
+    }
+    return { waveSize, dryRun, force, json };
+}
+function padWaveIndex(index) {
+    return index.toString().padStart(2, "0");
+}
+function buildWaveFileBody(waveIndex, units, sourceLabel) {
+    const idsRange = `${units[0].id}..${units[units.length - 1].id}`;
+    return [
+        `# Wave ${padWaveIndex(waveIndex)}`,
+        "",
+        `Source: ${sourceLabel} units ${idsRange}`,
+        "",
+        "## Implementation Units",
+        "",
+        units.map((unit) => unit.body.trim()).join("\n\n"),
+        ""
+    ].join("\n");
+}
+function buildWavePlansSection(waveFiles) {
+    const lines = [];
+    lines.push(WAVE_MANAGED_START);
+    lines.push("## Wave Plans");
+    lines.push("");
+    for (let i = 0; i < waveFiles.length; i += 1) {
+        lines.push(`- Wave ${padWaveIndex(i + 1)}: \`${waveFiles[i]}\``);
+    }
+    lines.push("");
+    lines.push(WAVE_MANAGED_END);
+    return lines.join("\n");
+}
+/**
+ * Replace any existing managed Wave Plans block with the new one, or append
+ * it at the end of the file when no markers are present yet. The helper
+ * never touches text outside the markers.
+ */
+export function upsertWavePlansSection(planMarkdown, managedBlock) {
+    const startIdx = planMarkdown.indexOf(WAVE_MANAGED_START);
+    const endIdx = planMarkdown.indexOf(WAVE_MANAGED_END);
+    if (startIdx >= 0 && endIdx > startIdx) {
+        const before = planMarkdown.slice(0, startIdx);
+        const after = planMarkdown.slice(endIdx + WAVE_MANAGED_END.length);
+        const joined = `${before}${managedBlock}${after}`;
+        return joined.endsWith("\n") ? joined : `${joined}\n`;
+    }
+    const trimmed = planMarkdown.replace(/\s+$/u, "");
+    return `${trimmed}\n\n${managedBlock}\n`;
+}
+export async function runPlanSplitWaves(projectRoot, args, io) {
+    const flow = await readFlowState(projectRoot).catch(() => null);
+    const track = flow?.track;
+    const planResolved = await resolveArtifactPath("plan", {
+        projectRoot,
+        track,
+        intent: "read"
+    });
+    if (!(await exists(planResolved.absPath))) {
+        io.stderr.write(`cclaw internal plan-split-waves: plan artifact not found at ${planResolved.relPath}.\n`);
+        return 1;
+    }
+    const raw = await fs.readFile(planResolved.absPath, "utf8");
+    const units = parseImplementationUnits(raw);
+    if (units.length < PLAN_SPLIT_SMALL_PLAN_THRESHOLD) {
+        const outcome = {
+            ok: true,
+            command: "plan-split-waves",
+            totalUnits: units.length,
+            waveCount: 0,
+            waveSize: args.waveSize,
+            smallPlanNoOp: true,
+            dryRun: args.dryRun,
+            waveFiles: [],
+            planUpdated: false
+        };
+        if (args.json) {
+            io.stdout.write(`${JSON.stringify(outcome)}\n`);
+        }
+        else {
+            io.stdout.write(`plan is small (${units.length} unit(s), threshold ${PLAN_SPLIT_SMALL_PLAN_THRESHOLD}); no wave split needed.\n`);
+        }
+        return 0;
+    }
+    const waves = [];
+    for (let i = 0; i < units.length; i += args.waveSize) {
+        waves.push(units.slice(i, i + args.waveSize));
+    }
+    const artifactsDir = path.dirname(planResolved.absPath);
+    const wavePlansAbsDir = path.join(artifactsDir, WAVE_PLANS_DIR);
+    const waveFileNames = waves.map((_, idx) => `${WAVE_PLANS_DIR}/wave-${padWaveIndex(idx + 1)}.md`);
+    if (!args.dryRun && !args.force) {
+        for (const fileName of waveFileNames) {
+            const abs = path.join(artifactsDir, fileName);
+            if (await exists(abs)) {
+                io.stderr.write(`cclaw internal plan-split-waves: wave file already exists: ${path.relative(projectRoot, abs)}. Pass --force to overwrite.\n`);
+                return 1;
+            }
+        }
+    }
+    if (!args.dryRun) {
+        await fs.mkdir(wavePlansAbsDir, { recursive: true });
+        for (let i = 0; i < waves.length; i += 1) {
+            const fileName = waveFileNames[i];
+            const body = buildWaveFileBody(i + 1, waves[i], planResolved.fileName);
+            await writeFileSafe(path.join(artifactsDir, fileName), body);
+        }
+        const managed = buildWavePlansSection(waveFileNames);
+        const updatedPlan = upsertWavePlansSection(raw, managed);
+        if (updatedPlan !== raw) {
+            await writeFileSafe(planResolved.absPath, updatedPlan);
+        }
+    }
+    const outcome = {
+        ok: true,
+        command: "plan-split-waves",
+        totalUnits: units.length,
+        waveCount: waves.length,
+        waveSize: args.waveSize,
+        smallPlanNoOp: false,
+        dryRun: args.dryRun,
+        waveFiles: waveFileNames,
+        planUpdated: !args.dryRun
+    };
+    if (args.json) {
+        io.stdout.write(`${JSON.stringify(outcome)}\n`);
+    }
+    else if (args.dryRun) {
+        io.stdout.write(`dry run: would split ${units.length} unit(s) into ${waves.length} wave file(s) of size ${args.waveSize}:\n`);
+        for (const fileName of waveFileNames) {
+            io.stdout.write(`  - ${fileName}\n`);
+        }
+    }
+    else {
+        io.stdout.write(`wrote ${waves.length} wave file(s) under ${path.relative(projectRoot, wavePlansAbsDir)} and refreshed Wave Plans section in ${planResolved.relPath}.\n`);
+    }
+    return 0;
+}

package/dist/tdd-slices.d.ts

@@ -0,0 +1,90 @@
+/**
+ * v6.10.0 — sidecar ledger that replaces the per-slice markdown tables in
+ * `06-tdd.md` (Watched-RED Proof, Vertical Slice Cycle, RED/GREEN Evidence).
+ *
+ * The file lives next to the TDD artifact (`<artifacts-dir>/06-tdd-slices.jsonl`)
+ * and is append-only — every CLI call writes a new row, and consumers fold
+ * rows by `sliceId` taking the latest entry (by file order). Markdown tables
+ * remain a legacy fallback when this sidecar is absent or empty.
+ */
+export interface TddSliceLedgerEntry {
+    runId: string;
+    sliceId: string;
+    status: "red" | "green" | "refactor-deferred" | "refactor-done";
+    testFile: string;
+    testCommand: string;
+    redObservedAt?: string;
+    redOutputRef?: string;
+    greenAt?: string;
+    greenOutputRef?: string;
+    refactorAt?: string;
+    refactorRationale?: string;
+    claimedPaths: string[];
+    acceptanceCriterionId?: string;
+    planUnitId?: string;
+    schemaVersion: 1;
+}
+export declare const TDD_SLICE_LEDGER_FILENAME = "06-tdd-slices.jsonl";
+export declare const TDD_SLICE_LEDGER_SCHEMA_VERSION: 1;
+export declare const TDD_SLICE_STATUSES: readonly ["red", "green", "refactor-deferred", "refactor-done"];
+export type TddSliceStatus = (typeof TDD_SLICE_STATUSES)[number];
+/**
+ * Resolve `<artifacts-dir>/06-tdd-slices.jsonl`. Mirrors the convention used
+ * by the rest of the runtime (see `artifact-paths.ts::searchRoots`): the
+ * sidecar always lives under `.cclaw/artifacts/` regardless of the active
+ * topic slug for the TDD artifact.
+ */
+export declare function tddSliceLedgerPath(projectRoot: string): string;
+export declare function isTddSliceLedgerEntry(value: unknown): value is TddSliceLedgerEntry;
+export declare function readTddSliceLedger(projectRoot: string): Promise<{
+    entries: TddSliceLedgerEntry[];
+    corruptLines: number[];
+}>;
+/**
+ * Latest-row-wins fold by `sliceId`. Returns one entry per slice, ordered by
+ * the index of its latest row. Mirrors the pattern used by
+ * `computeActiveSubagents` for the delegation ledger.
+ */
+export declare function foldTddSliceLedger(entries: TddSliceLedgerEntry[]): TddSliceLedgerEntry[];
+/**
+ * Atomic append under a directory lock — reuses the same `withDirectoryLock`
+ * primitive that `appendDelegation` uses so concurrent CLI invocations don't
+ * tear a half-written JSON line.
+ */
+export declare function appendSliceEntry(projectRoot: string, entry: TddSliceLedgerEntry): Promise<void>;
+export interface TddSliceRecordArgs {
+    sliceId: string;
+    status: TddSliceStatus;
+    testFile?: string;
+    testCommand?: string;
+    claimedPaths?: string[];
+    redOutputRef?: string;
+    greenOutputRef?: string;
+    redObservedAt?: string;
+    greenAt?: string;
+    refactorAt?: string;
+    refactorRationale?: string;
+    acceptanceCriterionId?: string;
+    planUnitId?: string;
+    json: boolean;
+}
+export declare function parseTddSliceRecordArgs(tokens: string[]): TddSliceRecordArgs;
+interface TddSliceRecordIo {
+    stdout: {
+        write(chunk: string): boolean;
+    };
+    stderr: {
+        write(chunk: string): boolean;
+    };
+}
+/**
+ * Consume parsed CLI flags, fold against the existing sidecar to inherit
+ * fields recorded on earlier rows of the same slice, auto-stamp the
+ * status-relevant timestamp when not provided, and append the new row.
+ *
+ * The CLI surface is intentionally lenient: only the very first call for a
+ * slice (status=red) needs `--test-file`, `--command`, `--paths`. Subsequent
+ * green/refactor calls inherit those values from the latest prior row.
+ */
+export declare function runTddSliceRecord(projectRoot: string, args: TddSliceRecordArgs, io: TddSliceRecordIo): Promise<number>;
+export {};