cclaw-cli 7.1.1 → 7.3.0

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

@@ -3,6 +3,7 @@ import { RUNTIME_ROOT } from "../../constants.js";
 import { stageSchema } from "../../content/stage-schema.js";
 import { readFlowState } from "../../runs.js";
 import { TRACK_STAGES } from "../../types.js";
+import { STACK_DISCOVERY_DIR_MARKERS, STACK_DISCOVERY_MARKERS } from "../../stack-detection.js";
 import { coerceCandidateFlowState } from "./flow-state-coercion.js";
 import { buildValidationReport } from "./advance.js";
 import fs from "node:fs/promises";
@@ -171,24 +172,11 @@ export async function discoverStartFlowContext(projectRoot) {
     lines.push(originFiles.length > 0
         ? `- Origin docs scanned: found ${originFiles.join(", ")}.`
         : "- Origin docs scanned: no PRD/RFC/ADR/design/spec files found in configured locations.");
-    const stackMarkers = await listExistingFiles(projectRoot, [
-        "package.json",
-        "pyproject.toml",
-        "requirements.txt",
-        "requirements-dev.txt",
-        ".python-version",
-        "go.mod",
-        "Cargo.toml",
-        "pom.xml",
-        "build.gradle",
-        "build.gradle.kts",
-        "Dockerfile",
-        "docker-compose.yml",
-        "docker-compose.yaml",
-        ".gitlab-ci.yml"
-    ]);
-    if (await pathExists(projectRoot, ".github/workflows")) {
-        stackMarkers.push(".github/workflows/");
+    const stackMarkers = await listExistingFiles(projectRoot, [...STACK_DISCOVERY_MARKERS]);
+    for (const markerDir of STACK_DISCOVERY_DIR_MARKERS) {
+        if (await pathExists(projectRoot, markerDir)) {
+            stackMarkers.push(`${markerDir}/`);
+        }
     }
     lines.push(stackMarkers.length > 0
         ? `- Stack markers scanned: found ${stackMarkers.join(", ")}.`

package/dist/internal/slice-commit.js

@@ -1,9 +1,10 @@
 import { execFile } from "node:child_process";
 import path from "node:path";
 import { promisify } from "node:util";
-import { readConfig, resolveTddCommitMode } from "../config.js";
+import { readConfig, resolveTddCommitMode, resolveTddIsolationMode, resolveTddWorktreeRoot } from "../config.js";
 import { readDelegationLedger } from "../delegation.js";
 import { exists } from "../fs-utils.js";
+import { cleanupWorktree, commitAndMergeBack, createSliceWorktree, WorktreeMergeConflictError, WorktreeUnsupportedError } from "../worktree-manager.js";
 const execFileAsync = promisify(execFile);
 function parseCsv(raw) {
     return raw
@@ -22,7 +23,9 @@ function parseSliceCommitArgs(tokens) {
     let taskId;
     let title;
     let runId;
+    let worktreePath;
     const claimedPaths = [];
+    let prepareWorktree = false;
     let json = false;
     let quiet = false;
     for (let i = 0; i < tokens.length; i += 1) {
@@ -45,6 +48,10 @@ function parseSliceCommitArgs(tokens) {
             quiet = true;
             continue;
         }
+        if (token === "--prepare-worktree") {
+            prepareWorktree = true;
+            continue;
+        }
         if (token.startsWith("--slice=") || token === "--slice") {
             sliceId = valueFrom("--slice").trim();
             continue;
@@ -65,6 +72,13 @@ function parseSliceCommitArgs(tokens) {
             runId = valueFrom("--run-id").trim();
             continue;
         }
+        if (token.startsWith("--worktree-path=") || token === "--worktree-path") {
+            const resolved = valueFrom("--worktree-path").trim();
+            if (resolved.length > 0) {
+                worktreePath = resolved;
+            }
+            continue;
+        }
         if (token.startsWith("--claimed-paths=") || token === "--claimed-paths") {
             claimedPaths.push(...parseCsv(valueFrom("--claimed-paths")));
             continue;
@@ -89,7 +103,9 @@ function parseSliceCommitArgs(tokens) {
         taskId,
         title,
         runId,
+        worktreePath,
         claimedPaths,
+        prepareWorktree,
         json,
         quiet
     };
@@ -132,6 +148,12 @@ function parsePorcelainPaths(raw) {
     }
     return [...new Set(out)];
 }
+async function gitChangedPaths(cwd) {
+    const { stdout: statusRaw } = await execFileAsync("git", ["status", "--porcelain", "-uall"], {
+        cwd
+    });
+    return parsePorcelainPaths(statusRaw);
+}
 function matchesClaimedPath(changedPath, claimedPaths) {
     const changed = normalizePathLike(changedPath);
     return claimedPaths.some((rawClaimed) => {
@@ -171,6 +193,67 @@ export async function runSliceCommitCommand(projectRoot, tokens, io) {
     }
     const config = await readConfig(projectRoot).catch(() => null);
     const commitMode = resolveTddCommitMode(config);
+    const isolationMode = resolveTddIsolationMode(config);
+    const worktreeRoot = resolveTddWorktreeRoot(config);
+    const gitPresent = await exists(path.join(projectRoot, ".git"));
+    if (args.prepareWorktree) {
+        if (!gitPresent) {
+            output(io, args, {
+                ok: true,
+                skipped: true,
+                reason: "no-git",
+                message: "slice-worktree skipped: .git is missing"
+            });
+            return 0;
+        }
+        if (isolationMode === "in-place") {
+            output(io, args, {
+                ok: true,
+                skipped: true,
+                reason: "isolation-in-place",
+                isolationMode,
+                message: "slice-worktree skipped: tdd.isolationMode=in-place"
+            });
+            return 0;
+        }
+        try {
+            const { stdout } = await execFileAsync("git", ["rev-parse", "HEAD"], { cwd: projectRoot });
+            const prepared = await createSliceWorktree(args.sliceId, stdout.trim(), args.claimedPaths, {
+                projectRoot,
+                worktreeRoot
+            });
+            output(io, args, {
+                ok: true,
+                prepared: true,
+                sliceId: args.sliceId,
+                spanId: args.spanId,
+                worktreePath: prepared.path,
+                baseRef: prepared.ref
+            });
+            return 0;
+        }
+        catch (error) {
+            if (error instanceof WorktreeUnsupportedError) {
+                output(io, args, {
+                    ok: true,
+                    skipped: true,
+                    reason: "worktree-unavailable",
+                    degradedCommitMode: "agent-required",
+                    message: error.message
+                });
+                return 0;
+            }
+            output(io, args, {
+                ok: false,
+                errorCode: "worktree_prepare_failed",
+                details: {
+                    message: error instanceof Error ? error.message : String(error)
+                },
+                message: `worktree_prepare_failed: ${error instanceof Error ? error.message : String(error)}`
+            }, "stderr");
+            return 1;
+        }
+    }
     if (commitMode !== "managed-per-slice") {
         output(io, args, {
             ok: true,
@@ -181,7 +264,6 @@ export async function runSliceCommitCommand(projectRoot, tokens, io) {
         });
         return 0;
     }
-    const gitPresent = await exists(path.join(projectRoot, ".git"));
     if (!gitPresent) {
         output(io, args, {
             ok: true,
@@ -206,11 +288,64 @@ export async function runSliceCommitCommand(projectRoot, tokens, io) {
         }, "stderr");
         return 2;
     }
-    const { stdout: statusRaw } = await execFileAsync("git", ["status", "--porcelain", "-uall"], {
-        cwd: projectRoot
-    });
-    const changedPaths = parsePorcelainPaths(statusRaw);
+    let managedWorktreePath = null;
+    let activeCwd = projectRoot;
+    let degradedToInPlace = false;
+    const requestedWorktreePath = typeof args.worktreePath === "string" && args.worktreePath.trim().length > 0
+        ? path.resolve(projectRoot, args.worktreePath.trim())
+        : null;
+    if (requestedWorktreePath && await exists(requestedWorktreePath)) {
+        managedWorktreePath = requestedWorktreePath;
+        activeCwd = requestedWorktreePath;
+    }
+    else if (isolationMode !== "in-place") {
+        try {
+            const { stdout } = await execFileAsync("git", ["rev-parse", "HEAD"], { cwd: projectRoot });
+            const prepared = await createSliceWorktree(args.sliceId, stdout.trim(), claimedPaths, {
+                projectRoot,
+                worktreeRoot
+            });
+            managedWorktreePath = prepared.path;
+            activeCwd = prepared.path;
+        }
+        catch (error) {
+            if (error instanceof WorktreeUnsupportedError) {
+                output(io, args, {
+                    ok: true,
+                    skipped: true,
+                    reason: "worktree-unavailable",
+                    degradedCommitMode: "agent-required",
+                    message: error.message
+                });
+                return 0;
+            }
+            output(io, args, {
+                ok: false,
+                errorCode: "worktree_prepare_failed",
+                details: {
+                    message: error instanceof Error ? error.message : String(error)
+                },
+                message: `worktree_prepare_failed: ${error instanceof Error ? error.message : String(error)}`
+            }, "stderr");
+            return 1;
+        }
+    }
+    const cleanupManagedWorktree = async () => {
+        if (!managedWorktreePath)
+            return;
+        await cleanupWorktree(managedWorktreePath, { projectRoot }).catch(() => undefined);
+    };
+    let changedPaths = await gitChangedPaths(activeCwd);
+    if (changedPaths.length === 0 && managedWorktreePath && activeCwd !== projectRoot) {
+        const rootChangedPaths = await gitChangedPaths(projectRoot);
+        if (rootChangedPaths.length > 0) {
+            activeCwd = projectRoot;
+            changedPaths = rootChangedPaths;
+            degradedToInPlace = true;
+        }
+    }
     if (changedPaths.length === 0) {
+        await cleanupManagedWorktree();
         output(io, args, {
             ok: true,
             skipped: true,
@@ -236,6 +371,7 @@ export async function runSliceCommitCommand(projectRoot, tokens, io) {
     }
     const changedInClaim = changedPaths.filter((p) => matchesClaimedPath(p, claimedPaths));
     if (changedInClaim.length === 0) {
+        await cleanupManagedWorktree();
         output(io, args, {
             ok: true,
             skipped: true,
@@ -246,7 +382,7 @@ export async function runSliceCommitCommand(projectRoot, tokens, io) {
     }
     try {
         await execFileAsync("git", ["add", "--", ...claimedPaths], {
-            cwd: projectRoot
+            cwd: activeCwd
         });
         const taskPart = args.taskId && args.taskId.length > 0 ? args.taskId : "task";
         const titlePart = args.title && args.title.length > 0 ? args.title : "slice update";
@@ -257,12 +393,13 @@ export async function runSliceCommitCommand(projectRoot, tokens, io) {
             "phase-cycle: red->green->refactor->doc"
         ].join("\n");
         await execFileAsync("git", ["commit", "-m", header, "-m", body], {
-            cwd: projectRoot
+            cwd: activeCwd
         });
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         if (/nothing to commit/iu.test(message)) {
+            await cleanupManagedWorktree();
             output(io, args, {
                 ok: true,
                 skipped: true,
@@ -280,9 +417,39 @@ export async function runSliceCommitCommand(projectRoot, tokens, io) {
         return 1;
     }
     const { stdout: shaStdout } = await execFileAsync("git", ["rev-parse", "HEAD"], {
-        cwd: projectRoot
+        cwd: activeCwd
     });
-    const commitSha = shaStdout.trim();
+    let commitSha = shaStdout.trim();
+    if (managedWorktreePath && activeCwd !== projectRoot) {
+        try {
+            const merged = await commitAndMergeBack(activeCwd, `merge ${args.sliceId}`, { projectRoot });
+            commitSha = merged.commitSha;
+        }
+        catch (error) {
+            if (error instanceof WorktreeMergeConflictError) {
+                output(io, args, {
+                    ok: false,
+                    errorCode: "worktree_merge_conflict",
+                    details: {
+                        sliceId: args.sliceId,
+                        spanId: args.spanId,
+                        worktreePath: activeCwd,
+                        message: error.message
+                    },
+                    message: error.message
+                }, "stderr");
+                return 2;
+            }
+            output(io, args, {
+                ok: false,
+                errorCode: "slice_commit_failed",
+                details: { message: error instanceof Error ? error.message : String(error) },
+                message: `slice_commit_failed: ${error instanceof Error ? error.message : String(error)}`
+            }, "stderr");
+            return 1;
+        }
+    }
+    await cleanupManagedWorktree();
     output(io, args, {
         ok: true,
         commitSha,
@@ -290,6 +457,8 @@ export async function runSliceCommitCommand(projectRoot, tokens, io) {
         spanId: args.spanId,
         claimedPaths,
         changedPaths: changedInClaim,
+        worktreePath: managedWorktreePath ?? undefined,
+        degradedToInPlace: degradedToInPlace || undefined,
         message: `slice commit created for ${args.sliceId}: ${commitSha}`
     });
     return 0;

package/dist/runtime/run-hook.mjs

@@ -40,6 +40,7 @@ var REQUIRED_DIRS = [
   `${RUNTIME_ROOT}/artifacts`,
   `${RUNTIME_ROOT}/wave-plans`,
   `${RUNTIME_ROOT}/archive`,
+  `${RUNTIME_ROOT}/worktrees`,
   `${RUNTIME_ROOT}/state`,
   `${RUNTIME_ROOT}/rules`,
   `${RUNTIME_ROOT}/agents`,

package/dist/stack-detection.d.ts

@@ -0,0 +1,22 @@
+export interface StackReviewRouteProfile {
+    stack: string;
+    /**
+     * Signals shown in review routing documentation/skills.
+     * These are human-facing pointers, not strict parsers.
+     */
+    reviewSignals: string[];
+    /** Root-level markers used by start-flow context discovery. */
+    discoveryMarkers: string[];
+    focus: string;
+}
+export declare const STACK_REVIEW_ROUTE_PROFILES: readonly StackReviewRouteProfile[];
+/**
+ * Unified root-marker list used by start-flow context discovery.
+ * Keep this in one place so stage skill routing and start-flow scanning
+ * evolve together.
+ */
+export declare const STACK_DISCOVERY_MARKERS: readonly string[];
+/**
+ * Directory markers (checked with pathExists) for stack discovery.
+ */
+export declare const STACK_DISCOVERY_DIR_MARKERS: readonly string[];

package/dist/stack-detection.js

@@ -0,0 +1,58 @@
+export const STACK_REVIEW_ROUTE_PROFILES = [
+    {
+        stack: "TypeScript/JavaScript",
+        reviewSignals: ["package.json", "tsconfig.json"],
+        discoveryMarkers: ["package.json", "tsconfig.json", "jsconfig.json"],
+        focus: "type safety, package scripts, build/test config, dependency boundaries"
+    },
+    {
+        stack: "Python",
+        reviewSignals: ["pyproject.toml", "requirements.txt"],
+        discoveryMarkers: ["pyproject.toml", "requirements.txt", "requirements-dev.txt", ".python-version"],
+        focus: "packaging, virtualenv assumptions, typing, pytest or unittest evidence"
+    },
+    {
+        stack: "Ruby/Rails",
+        reviewSignals: ["Gemfile", "config/"],
+        discoveryMarkers: ["Gemfile"],
+        focus: "Rails conventions, migrations, routes/controllers, RSpec or Minitest evidence"
+    },
+    {
+        stack: "Go",
+        reviewSignals: ["go.mod"],
+        discoveryMarkers: ["go.mod"],
+        focus: "interfaces, concurrency, error handling, go test coverage"
+    },
+    {
+        stack: "Rust",
+        reviewSignals: ["Cargo.toml"],
+        discoveryMarkers: ["Cargo.toml"],
+        focus: "ownership, error/result handling, feature flags, cargo test coverage"
+    }
+];
+const EXTRA_DISCOVERY_MARKERS = [
+    "pom.xml",
+    "build.gradle",
+    "build.gradle.kts",
+    "Dockerfile",
+    "docker-compose.yml",
+    "docker-compose.yaml",
+    ".gitlab-ci.yml"
+];
+/**
+ * Unified root-marker list used by start-flow context discovery.
+ * Keep this in one place so stage skill routing and start-flow scanning
+ * evolve together.
+ */
+export const STACK_DISCOVERY_MARKERS = [
+    ...new Set([
+        ...STACK_REVIEW_ROUTE_PROFILES.flatMap((profile) => profile.discoveryMarkers),
+        ...EXTRA_DISCOVERY_MARKERS
+    ])
+];
+/**
+ * Directory markers (checked with pathExists) for stack discovery.
+ */
+export const STACK_DISCOVERY_DIR_MARKERS = [
+    ".github/workflows"
+];

package/dist/types.d.ts

@@ -162,6 +162,7 @@ export interface ReviewLoopConfig {
 }
 export type VcsMode = "git-with-remote" | "git-local-only" | "none";
 export type TddCommitMode = "managed-per-slice" | "agent-required" | "checkpoint-only" | "off";
+export type TddIsolationMode = "worktree" | "in-place" | "auto";
 export interface TddConfig {
     /**
      * Commit ownership model for closed TDD slices.
@@ -171,6 +172,17 @@ export interface TddConfig {
      * - off: skip commit-shape enforcement.
      */
     commitMode?: TddCommitMode;
+    /**
+     * Slice execution isolation model.
+     * - worktree: default; allocate one git worktree per slice span.
+     * - in-place: run in the main working tree.
+     * - auto: prefer worktree, degrade to in-place when unavailable.
+     */
+    isolationMode?: TddIsolationMode;
+    /**
+     * Repo-relative root used for managed slice worktrees.
+     */
+    worktreeRoot?: string;
 }
 export interface CclawConfig {
     version: string;

package/dist/worktree-manager.d.ts

@@ -0,0 +1,20 @@
+export interface WorktreeManagerOptions {
+    projectRoot?: string;
+    worktreeRoot?: string;
+}
+export declare class WorktreeUnsupportedError extends Error {
+    readonly code = "worktree_unavailable";
+    constructor(message: string);
+}
+export declare class WorktreeMergeConflictError extends Error {
+    readonly code = "worktree_merge_conflict";
+    constructor(message: string);
+}
+export declare function createSliceWorktree(sliceId: string, baseRef: string, _claimedPaths: string[], options?: WorktreeManagerOptions): Promise<{
+    path: string;
+    ref: string;
+}>;
+export declare function commitAndMergeBack(worktreePath: string, _message: string, options?: WorktreeManagerOptions): Promise<{
+    commitSha: string;
+}>;
+export declare function cleanupWorktree(worktreePath: string, options?: WorktreeManagerOptions): Promise<void>;

package/dist/worktree-manager.js

@@ -0,0 +1,108 @@
+import { execFile } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+import { DEFAULT_TDD_WORKTREE_ROOT } from "./config.js";
+import { exists } from "./fs-utils.js";
+const execFileAsync = promisify(execFile);
+export class WorktreeUnsupportedError extends Error {
+    code = "worktree_unavailable";
+    constructor(message) {
+        super(message);
+        this.name = "WorktreeUnsupportedError";
+    }
+}
+export class WorktreeMergeConflictError extends Error {
+    code = "worktree_merge_conflict";
+    constructor(message) {
+        super(message);
+        this.name = "WorktreeMergeConflictError";
+    }
+}
+function sanitizeSliceId(sliceId) {
+    return sliceId.trim().replace(/[^A-Za-z0-9._-]+/gu, "-");
+}
+function resolveProjectRoot(options) {
+    return options?.projectRoot ?? process.cwd();
+}
+function resolveWorktreeRoot(projectRoot, options) {
+    const root = typeof options?.worktreeRoot === "string" && options.worktreeRoot.trim().length > 0
+        ? options.worktreeRoot.trim()
+        : DEFAULT_TDD_WORKTREE_ROOT;
+    return path.resolve(projectRoot, root);
+}
+async function resolveMainRepoRootFromWorktree(worktreePath) {
+    const { stdout } = await execFileAsync("git", ["rev-parse", "--path-format=absolute", "--git-common-dir"], { cwd: worktreePath });
+    const commonDir = stdout.trim();
+    if (commonDir.length === 0) {
+        throw new Error(`Cannot resolve git common-dir from worktree ${worktreePath}`);
+    }
+    return path.dirname(commonDir);
+}
+export async function createSliceWorktree(sliceId, baseRef, _claimedPaths, options = {}) {
+    const projectRoot = resolveProjectRoot(options);
+    const ref = baseRef.trim().length > 0 ? baseRef.trim() : "HEAD";
+    const worktreeRoot = resolveWorktreeRoot(projectRoot, options);
+    const safeSliceId = sanitizeSliceId(sliceId);
+    if (safeSliceId.length === 0) {
+        throw new WorktreeUnsupportedError("Cannot create worktree: empty slice id.");
+    }
+    const worktreePath = path.join(worktreeRoot, safeSliceId);
+    try {
+        await execFileAsync("git", ["rev-parse", "--git-dir"], { cwd: projectRoot });
+    }
+    catch {
+        throw new WorktreeUnsupportedError("Cannot create worktree: repository has no .git metadata.");
+    }
+    await fs.mkdir(worktreeRoot, { recursive: true });
+    if (await exists(worktreePath)) {
+        if (await exists(path.join(worktreePath, ".git"))) {
+            return { path: worktreePath, ref };
+        }
+        await fs.rm(worktreePath, { recursive: true, force: true });
+    }
+    try {
+        await execFileAsync("git", ["worktree", "add", "--detach", worktreePath, ref], {
+            cwd: projectRoot
+        });
+    }
+    catch (error) {
+        throw new WorktreeUnsupportedError(`Cannot create worktree for ${sliceId}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return { path: worktreePath, ref };
+}
+export async function commitAndMergeBack(worktreePath, _message, options = {}) {
+    const projectRoot = options.projectRoot ?? await resolveMainRepoRootFromWorktree(worktreePath);
+    try {
+        const { stdout: mainHeadStdout } = await execFileAsync("git", ["rev-parse", "HEAD"], {
+            cwd: projectRoot
+        });
+        const mainHead = mainHeadStdout.trim();
+        await execFileAsync("git", ["rebase", mainHead], { cwd: worktreePath });
+        const { stdout } = await execFileAsync("git", ["rev-parse", "HEAD"], { cwd: worktreePath });
+        const commitSha = stdout.trim();
+        await execFileAsync("git", ["fetch", worktreePath, "HEAD"], { cwd: projectRoot });
+        await execFileAsync("git", ["merge", "--ff-only", "FETCH_HEAD"], { cwd: projectRoot });
+        return { commitSha };
+    }
+    catch (error) {
+        throw new WorktreeMergeConflictError(`worktree_merge_conflict: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+export async function cleanupWorktree(worktreePath, options = {}) {
+    if (!(await exists(worktreePath)))
+        return;
+    const projectRoot = options.projectRoot ?? await resolveMainRepoRootFromWorktree(worktreePath).catch(() => null);
+    if (projectRoot) {
+        try {
+            await execFileAsync("git", ["worktree", "remove", "--force", worktreePath], {
+                cwd: projectRoot
+            });
+            return;
+        }
+        catch {
+            // fall through to rm fallback below
+        }
+    }
+    await fs.rm(worktreePath, { recursive: true, force: true });
+}

package/package.json

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