sequant 1.1.2 → 1.2.0

package/dist/src/commands/run.js

@@ -6,10 +6,213 @@
  */
 import chalk from "chalk";
 import { spawnSync } from "child_process";
+import { existsSync } from "fs";
+import path from "path";
 import { query } from "@anthropic-ai/claude-agent-sdk";
 import { getManifest } from "../lib/manifest.js";
+import { getSettings } from "../lib/settings.js";
+import { PM_CONFIG } from "../lib/stacks.js";
 import { LogWriter, createPhaseLogFromTiming, } from "../lib/workflow/log-writer.js";
 import { DEFAULT_PHASES, DEFAULT_CONFIG, } from "../lib/workflow/types.js";
+/**
+ * Slugify a title for branch naming
+ */
+function slugify(title) {
+    return title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .substring(0, 50);
+}
+/**
+ * Get the git repository root directory
+ */
+function getGitRoot() {
+    const result = spawnSync("git", ["rev-parse", "--show-toplevel"], {
+        stdio: "pipe",
+    });
+    if (result.status === 0) {
+        return result.stdout.toString().trim();
+    }
+    return null;
+}
+/**
+ * Check if a worktree exists for a given branch
+ */
+function findExistingWorktree(branch) {
+    const result = spawnSync("git", ["worktree", "list", "--porcelain"], {
+        stdio: "pipe",
+    });
+    if (result.status !== 0)
+        return null;
+    const output = result.stdout.toString();
+    const lines = output.split("\n");
+    let currentPath = "";
+    for (const line of lines) {
+        if (line.startsWith("worktree ")) {
+            currentPath = line.substring(9);
+        }
+        else if (line.startsWith("branch refs/heads/") && line.includes(branch)) {
+            return currentPath;
+        }
+    }
+    return null;
+}
+/**
+ * List all active worktrees with their branches
+ */
+export function listWorktrees() {
+    const result = spawnSync("git", ["worktree", "list", "--porcelain"], {
+        stdio: "pipe",
+    });
+    if (result.status !== 0)
+        return [];
+    const output = result.stdout.toString();
+    const lines = output.split("\n");
+    const worktrees = [];
+    let currentPath = "";
+    let currentBranch = "";
+    for (const line of lines) {
+        if (line.startsWith("worktree ")) {
+            currentPath = line.substring(9);
+        }
+        else if (line.startsWith("branch refs/heads/")) {
+            currentBranch = line.substring(18);
+            // Extract issue number from branch name (e.g., feature/123-some-title)
+            const issueMatch = currentBranch.match(/feature\/(\d+)-/);
+            const issue = issueMatch ? parseInt(issueMatch[1], 10) : null;
+            worktrees.push({ path: currentPath, branch: currentBranch, issue });
+            currentPath = "";
+            currentBranch = "";
+        }
+    }
+    return worktrees;
+}
+/**
+ * Get changed files in a worktree compared to main
+ */
+export function getWorktreeChangedFiles(worktreePath) {
+    const result = spawnSync("git", ["-C", worktreePath, "diff", "--name-only", "main...HEAD"], { stdio: "pipe" });
+    if (result.status !== 0)
+        return [];
+    return result.stdout
+        .toString()
+        .trim()
+        .split("\n")
+        .filter((f) => f.length > 0);
+}
+/**
+ * Create or reuse a worktree for an issue
+ */
+async function ensureWorktree(issueNumber, title, verbose, packageManager) {
+    const gitRoot = getGitRoot();
+    if (!gitRoot) {
+        console.log(chalk.red("    ❌ Not in a git repository"));
+        return null;
+    }
+    const slug = slugify(title);
+    const branch = `feature/${issueNumber}-${slug}`;
+    const worktreesDir = path.join(path.dirname(gitRoot), "worktrees");
+    const worktreePath = path.join(worktreesDir, branch);
+    // Check if worktree already exists
+    const existingPath = findExistingWorktree(branch);
+    if (existingPath) {
+        if (verbose) {
+            console.log(chalk.gray(`    📂 Reusing existing worktree: ${existingPath}`));
+        }
+        return {
+            issue: issueNumber,
+            path: existingPath,
+            branch,
+            existed: true,
+        };
+    }
+    // Check if branch exists (but no worktree)
+    const branchCheck = spawnSync("git", ["show-ref", "--verify", "--quiet", `refs/heads/${branch}`], { stdio: "pipe" });
+    const branchExists = branchCheck.status === 0;
+    if (verbose) {
+        console.log(chalk.gray(`    🌿 Creating worktree for #${issueNumber}...`));
+    }
+    // Ensure worktrees directory exists
+    if (!existsSync(worktreesDir)) {
+        spawnSync("mkdir", ["-p", worktreesDir], { stdio: "pipe" });
+    }
+    // Create the worktree
+    let createResult;
+    if (branchExists) {
+        // Use existing branch
+        createResult = spawnSync("git", ["worktree", "add", worktreePath, branch], {
+            stdio: "pipe",
+        });
+    }
+    else {
+        // Create new branch from main
+        createResult = spawnSync("git", ["worktree", "add", worktreePath, "-b", branch], { stdio: "pipe" });
+    }
+    if (createResult.status !== 0) {
+        const error = createResult.stderr.toString();
+        console.log(chalk.red(`    ❌ Failed to create worktree: ${error}`));
+        return null;
+    }
+    // Copy .env.local if it exists
+    const envLocalSrc = path.join(gitRoot, ".env.local");
+    const envLocalDst = path.join(worktreePath, ".env.local");
+    if (existsSync(envLocalSrc) && !existsSync(envLocalDst)) {
+        spawnSync("cp", [envLocalSrc, envLocalDst], { stdio: "pipe" });
+    }
+    // Copy .claude/settings.local.json if it exists
+    const claudeSettingsSrc = path.join(gitRoot, ".claude", "settings.local.json");
+    const claudeSettingsDst = path.join(worktreePath, ".claude", "settings.local.json");
+    if (existsSync(claudeSettingsSrc) && !existsSync(claudeSettingsDst)) {
+        spawnSync("mkdir", ["-p", path.join(worktreePath, ".claude")], {
+            stdio: "pipe",
+        });
+        spawnSync("cp", [claudeSettingsSrc, claudeSettingsDst], { stdio: "pipe" });
+    }
+    // Install dependencies if needed
+    const nodeModulesPath = path.join(worktreePath, "node_modules");
+    if (!existsSync(nodeModulesPath)) {
+        if (verbose) {
+            console.log(chalk.gray(`    📦 Installing dependencies...`));
+        }
+        // Use detected package manager or default to npm
+        const pm = packageManager || "npm";
+        const pmConfig = PM_CONFIG[pm];
+        const [cmd, ...args] = pmConfig.installSilent.split(" ");
+        spawnSync(cmd, args, {
+            cwd: worktreePath,
+            stdio: "pipe",
+        });
+    }
+    if (verbose) {
+        console.log(chalk.green(`    ✅ Worktree ready: ${worktreePath}`));
+    }
+    return {
+        issue: issueNumber,
+        path: worktreePath,
+        branch,
+        existed: false,
+    };
+}
+/**
+ * Ensure worktrees exist for all issues before execution
+ */
+async function ensureWorktrees(issues, verbose, packageManager) {
+    const worktrees = new Map();
+    console.log(chalk.blue("\n  📂 Preparing worktrees..."));
+    for (const issue of issues) {
+        const worktree = await ensureWorktree(issue.number, issue.title, verbose, packageManager);
+        if (worktree) {
+            worktrees.set(issue.number, worktree);
+        }
+    }
+    const created = Array.from(worktrees.values()).filter((w) => !w.existed).length;
+    const reused = Array.from(worktrees.values()).filter((w) => w.existed).length;
+    if (created > 0 || reused > 0) {
+        console.log(chalk.gray(`  Worktrees: ${created} created, ${reused} reused`));
+    }
+    return worktrees;
+}
 /**
  * Natural language prompts for each phase
  * These prompts will invoke the corresponding skills via natural language
@@ -26,6 +229,84 @@ const PHASE_PROMPTS = {
  * UI-related labels that trigger automatic test phase
  */
 const UI_LABELS = ["ui", "frontend", "admin", "web", "browser"];
+/**
+ * Bug-related labels that skip spec phase
+ */
+const BUG_LABELS = ["bug", "fix", "hotfix", "patch"];
+/**
+ * Documentation labels that skip spec phase
+ */
+const DOCS_LABELS = ["docs", "documentation", "readme"];
+/**
+ * Complex labels that enable quality loop
+ */
+const COMPLEX_LABELS = ["complex", "refactor", "breaking", "major"];
+/**
+ * Detect phases based on issue labels (like /solve logic)
+ */
+function detectPhasesFromLabels(labels) {
+    const lowerLabels = labels.map((l) => l.toLowerCase());
+    // Check for bug/fix labels → exec → qa (skip spec)
+    const isBugFix = lowerLabels.some((label) => BUG_LABELS.some((bugLabel) => label.includes(bugLabel)));
+    // Check for docs labels → exec → qa (skip spec)
+    const isDocs = lowerLabels.some((label) => DOCS_LABELS.some((docsLabel) => label.includes(docsLabel)));
+    // Check for UI labels → add test phase
+    const isUI = lowerLabels.some((label) => UI_LABELS.some((uiLabel) => label.includes(uiLabel)));
+    // Check for complex labels → enable quality loop
+    const isComplex = lowerLabels.some((label) => COMPLEX_LABELS.some((complexLabel) => label.includes(complexLabel)));
+    // Build phase list
+    let phases;
+    if (isBugFix || isDocs) {
+        // Simple workflow: exec → qa
+        phases = ["exec", "qa"];
+    }
+    else if (isUI) {
+        // UI workflow: spec → exec → test → qa
+        phases = ["spec", "exec", "test", "qa"];
+    }
+    else {
+        // Standard workflow: spec → exec → qa
+        phases = ["spec", "exec", "qa"];
+    }
+    return { phases, qualityLoop: isComplex };
+}
+/**
+ * Parse recommended workflow from /spec output
+ *
+ * Looks for:
+ * ## Recommended Workflow
+ * **Phases:** exec → qa
+ * **Quality Loop:** enabled|disabled
+ */
+function parseRecommendedWorkflow(output) {
+    // Find the Recommended Workflow section
+    const workflowMatch = output.match(/## Recommended Workflow[\s\S]*?\*\*Phases:\*\*\s*([^\n]+)/i);
+    if (!workflowMatch) {
+        return null;
+    }
+    // Parse phases from "exec → qa" or "spec → exec → test → qa" format
+    const phasesStr = workflowMatch[1].trim();
+    const phaseNames = phasesStr
+        .split(/\s*→\s*|\s*->\s*|\s*,\s*/)
+        .map((p) => p.trim().toLowerCase())
+        .filter((p) => p.length > 0);
+    // Validate and convert to Phase type
+    const validPhases = [];
+    for (const name of phaseNames) {
+        if (["spec", "testgen", "exec", "test", "qa", "loop"].includes(name)) {
+            validPhases.push(name);
+        }
+    }
+    if (validPhases.length === 0) {
+        return null;
+    }
+    // Parse quality loop setting
+    const qualityLoopMatch = output.match(/\*\*Quality Loop:\*\*\s*(enabled|disabled|true|false|yes|no)/i);
+    const qualityLoop = qualityLoopMatch
+        ? ["enabled", "true", "yes"].includes(qualityLoopMatch[1].toLowerCase())
+        : false;
+    return { phases: validPhases, qualityLoop };
+}
 /**
  * Format duration in human-readable format
  */
@@ -43,10 +324,15 @@ function formatDuration(seconds) {
 function getPhasePrompt(phase, issueNumber) {
     return PHASE_PROMPTS[phase].replace(/\{issue\}/g, String(issueNumber));
 }
+/**
+ * Phases that require worktree isolation (exec, test, qa)
+ * Spec runs in main repo since it's planning-only
+ */
+const ISOLATED_PHASES = ["exec", "test", "qa"];
 /**
  * Execute a single phase for an issue using Claude Agent SDK
  */
-async function executePhase(issueNumber, phase, config, sessionId) {
+async function executePhase(issueNumber, phase, config, sessionId, worktreePath) {
     const startTime = Date.now();
     if (config.dryRun) {
         // Dry run - just simulate
@@ -62,7 +348,13 @@ async function executePhase(issueNumber, phase, config, sessionId) {
     const prompt = getPhasePrompt(phase, issueNumber);
     if (config.verbose) {
         console.log(chalk.gray(`    Prompt: ${prompt}`));
+        if (worktreePath && ISOLATED_PHASES.includes(phase)) {
+            console.log(chalk.gray(`    Worktree: ${worktreePath}`));
+        }
     }
+    // Determine working directory and environment
+    const shouldUseWorktree = worktreePath && ISOLATED_PHASES.includes(phase);
+    const cwd = shouldUseWorktree ? worktreePath : process.cwd();
     try {
         // Create abort controller for timeout
         const abortController = new AbortController();
@@ -72,12 +364,25 @@ async function executePhase(issueNumber, phase, config, sessionId) {
         let resultSessionId;
         let resultMessage;
         let lastError;
+        let capturedOutput = "";
+        // Build environment with worktree isolation variables
+        const env = {
+            ...process.env,
+            CLAUDE_HOOKS_SMART_TESTS: config.noSmartTests ? "false" : "true",
+        };
+        // Set worktree isolation environment variables
+        if (shouldUseWorktree) {
+            env.SEQUANT_WORKTREE = worktreePath;
+            env.SEQUANT_ISSUE = String(issueNumber);
+        }
         // Execute using Claude Agent SDK
+        // Note: Don't resume sessions when switching to worktree (different cwd breaks resume)
+        const canResume = sessionId && !shouldUseWorktree;
         const queryInstance = query({
             prompt,
             options: {
                 abortController,
-                cwd: process.cwd(),
+                cwd,
                 // Load project settings including skills
                 settingSources: ["project"],
                 // Use Claude Code's system prompt and tools
@@ -86,13 +391,10 @@ async function executePhase(issueNumber, phase, config, sessionId) {
                 // Bypass permissions for headless execution
                 permissionMode: "bypassPermissions",
                 allowDangerouslySkipPermissions: true,
-                // Resume from previous session if provided
-                ...(sessionId ? { resume: sessionId } : {}),
-                // Configure smart tests via environment
-                env: {
-                    ...process.env,
-                    CLAUDE_HOOKS_SMART_TESTS: config.noSmartTests ? "false" : "true",
-                },
+                // Resume from previous session if provided (but not when switching directories)
+                ...(canResume ? { resume: sessionId } : {}),
+                // Configure smart tests and worktree isolation via environment
+                env,
             },
         });
         // Stream and process messages
@@ -101,8 +403,8 @@ async function executePhase(issueNumber, phase, config, sessionId) {
             if (message.type === "system" && message.subtype === "init") {
                 resultSessionId = message.session_id;
             }
-            // Show streaming output in verbose mode
-            if (config.verbose && message.type === "assistant") {
+            // Capture output from assistant messages
+            if (message.type === "assistant") {
                 // Extract text content from the message
                 const content = message.message.content;
                 const textContent = content
@@ -110,7 +412,11 @@ async function executePhase(issueNumber, phase, config, sessionId) {
                     .map((c) => c.text)
                     .join("");
                 if (textContent) {
-                    process.stdout.write(chalk.gray(textContent));
+                    capturedOutput += textContent;
+                    // Show streaming output in verbose mode
+                    if (config.verbose) {
+                        process.stdout.write(chalk.gray(textContent));
+                    }
                 }
             }
             // Capture the final result
@@ -128,6 +434,7 @@ async function executePhase(issueNumber, phase, config, sessionId) {
                     success: true,
                     durationSeconds,
                     sessionId: resultSessionId,
+                    output: capturedOutput,
                 };
             }
             else {
@@ -189,21 +496,14 @@ async function executePhase(issueNumber, phase, config, sessionId) {
  */
 async function getIssueInfo(issueNumber) {
     try {
-        const result = spawnSync("gh", [
-            "issue",
-            "view",
-            String(issueNumber),
-            "--json",
-            "title,labels",
-            "--jq",
-            '"\(.title)|\(.labels | map(.name) | join(","))"',
-        ], { stdio: "pipe", shell: true });
+        const result = spawnSync("gh", ["issue", "view", String(issueNumber), "--json", "title,labels"], { stdio: "pipe" });
         if (result.status === 0) {
-            const output = result.stdout.toString().trim().replace(/^"|"$/g, "");
-            const [title, labelsStr] = output.split("|");
+            const data = JSON.parse(result.stdout.toString());
             return {
-                title: title || `Issue #${issueNumber}`,
-                labels: labelsStr ? labelsStr.split(",").filter(Boolean) : [],
+                title: data.title || `Issue #${issueNumber}`,
+                labels: Array.isArray(data.labels)
+                    ? data.labels.map((l) => l.name)
+                    : [],
             };
         }
     }
@@ -212,6 +512,105 @@ async function getIssueInfo(issueNumber) {
     }
     return { title: `Issue #${issueNumber}`, labels: [] };
 }
+/**
+ * Parse dependencies from issue body and labels
+ * Returns array of issue numbers this issue depends on
+ */
+function parseDependencies(issueNumber) {
+    try {
+        const result = spawnSync("gh", ["issue", "view", String(issueNumber), "--json", "body,labels"], { stdio: "pipe" });
+        if (result.status !== 0)
+            return [];
+        const data = JSON.parse(result.stdout.toString());
+        const dependencies = [];
+        // Parse from body: "Depends on: #123" or "**Depends on**: #123"
+        if (data.body) {
+            const bodyMatch = data.body.match(/\*?\*?depends\s+on\*?\*?:?\s*#?(\d+)/gi);
+            if (bodyMatch) {
+                for (const match of bodyMatch) {
+                    const numMatch = match.match(/(\d+)/);
+                    if (numMatch) {
+                        dependencies.push(parseInt(numMatch[1], 10));
+                    }
+                }
+            }
+        }
+        // Parse from labels: "depends-on/123" or "depends-on-123"
+        if (data.labels && Array.isArray(data.labels)) {
+            for (const label of data.labels) {
+                const labelName = label.name || label;
+                const labelMatch = labelName.match(/depends-on[-/](\d+)/i);
+                if (labelMatch) {
+                    dependencies.push(parseInt(labelMatch[1], 10));
+                }
+            }
+        }
+        return [...new Set(dependencies)]; // Remove duplicates
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Sort issues by dependencies (topological sort)
+ * Issues with no dependencies come first, then issues that depend on them
+ */
+function sortByDependencies(issueNumbers) {
+    // Build dependency graph
+    const dependsOn = new Map();
+    for (const issue of issueNumbers) {
+        const deps = parseDependencies(issue);
+        // Only include dependencies that are in our issue list
+        dependsOn.set(issue, deps.filter((d) => issueNumbers.includes(d)));
+    }
+    // Topological sort using Kahn's algorithm
+    const inDegree = new Map();
+    for (const issue of issueNumbers) {
+        inDegree.set(issue, 0);
+    }
+    for (const deps of dependsOn.values()) {
+        for (const dep of deps) {
+            inDegree.set(dep, (inDegree.get(dep) || 0) + 1);
+        }
+    }
+    // Note: inDegree counts how many issues depend on each issue
+    // We want to process issues that nothing depends on last
+    // So we sort by: issues nothing depends on first, then dependent issues
+    const sorted = [];
+    const queue = [];
+    // Start with issues that have no dependencies
+    for (const issue of issueNumbers) {
+        const deps = dependsOn.get(issue) || [];
+        if (deps.length === 0) {
+            queue.push(issue);
+        }
+    }
+    const visited = new Set();
+    while (queue.length > 0) {
+        const issue = queue.shift();
+        if (visited.has(issue))
+            continue;
+        visited.add(issue);
+        sorted.push(issue);
+        // Find issues that depend on this one
+        for (const [other, deps] of dependsOn.entries()) {
+            if (deps.includes(issue) && !visited.has(other)) {
+                // Check if all dependencies of 'other' are satisfied
+                const allDepsSatisfied = deps.every((d) => visited.has(d));
+                if (allDepsSatisfied) {
+                    queue.push(other);
+                }
+            }
+        }
+    }
+    // Add any remaining issues (circular dependencies or unvisited)
+    for (const issue of issueNumbers) {
+        if (!visited.has(issue)) {
+            sorted.push(issue);
+        }
+    }
+    return sorted;
+}
 /**
  * Check if an issue has UI-related labels
  */
@@ -278,16 +677,34 @@ function parseBatches(batchArgs) {
  * Main run command
  */
 export async function runCommand(issues, options) {
-    console.log(chalk.blue("\n🚀 Sequant Workflow Execution\n"));
+    console.log(chalk.blue("\n🌐 Sequant Workflow Execution\n"));
     // Check if initialized
     const manifest = await getManifest();
     if (!manifest) {
         console.log(chalk.red("❌ Sequant is not initialized. Run `sequant init` first."));
         return;
     }
-    // Merge environment config with CLI options
+    // Load settings and merge with environment config and CLI options
+    const settings = await getSettings();
     const envConfig = getEnvConfig();
-    const mergedOptions = { ...envConfig, ...options };
+    // Settings provide defaults, env overrides settings, CLI overrides all
+    // Note: phases are auto-detected per-issue unless --phases is explicitly set
+    const mergedOptions = {
+        // Settings defaults (phases removed - now auto-detected)
+        sequential: options.sequential ?? settings.run.sequential,
+        timeout: options.timeout ?? settings.run.timeout,
+        logPath: options.logPath ?? settings.run.logPath,
+        qualityLoop: options.qualityLoop ?? settings.run.qualityLoop,
+        maxIterations: options.maxIterations ?? settings.run.maxIterations,
+        noSmartTests: options.noSmartTests ?? !settings.run.smartTests,
+        // Env overrides
+        ...envConfig,
+        // CLI explicit options override all
+        ...options,
+    };
+    // Determine if we should auto-detect phases from labels
+    const autoDetectPhases = !options.phases && settings.run.autoDetectPhases;
+    mergedOptions.autoDetectPhases = autoDetectPhases;
     // Parse issue numbers (or use batch mode)
     let issueNumbers;
     let batches = null;
@@ -301,17 +718,28 @@ export async function runCommand(issues, options) {
     }
     if (issueNumbers.length === 0) {
         console.log(chalk.red("❌ No valid issue numbers provided."));
-        console.log(chalk.gray("\nUsage: sequant run <issues...> [options]"));
-        console.log(chalk.gray("Example: sequant run 1 2 3 --sequential"));
-        console.log(chalk.gray('Batch example: sequant run --batch "1 2" --batch "3"'));
+        console.log(chalk.gray("\nUsage: npx sequant run <issues...> [options]"));
+        console.log(chalk.gray("Example: npx sequant run 1 2 3 --sequential"));
+        console.log(chalk.gray('Batch example: npx sequant run --batch "1 2" --batch "3"'));
         return;
     }
+    // Sort issues by dependencies (if more than one issue)
+    if (issueNumbers.length > 1 && !batches) {
+        const originalOrder = [...issueNumbers];
+        issueNumbers = sortByDependencies(issueNumbers);
+        const orderChanged = !originalOrder.every((n, i) => n === issueNumbers[i]);
+        if (orderChanged) {
+            console.log(chalk.gray(`  Dependency order: ${issueNumbers.map((n) => `#${n}`).join(" → ")}`));
+        }
+    }
     // Build config
+    // Note: config.phases is only used when --phases is explicitly set or autoDetect fails
+    const explicitPhases = mergedOptions.phases
+        ? mergedOptions.phases.split(",").map((p) => p.trim())
+        : null;
     const config = {
         ...DEFAULT_CONFIG,
-        phases: mergedOptions.phases
-            ? mergedOptions.phases.split(",").map((p) => p.trim())
-            : DEFAULT_PHASES,
+        phases: explicitPhases ?? DEFAULT_PHASES,
         sequential: mergedOptions.sequential ?? false,
         dryRun: mergedOptions.dryRun ?? false,
         verbose: mergedOptions.verbose ?? false,
@@ -321,8 +749,12 @@ export async function runCommand(issues, options) {
         noSmartTests: mergedOptions.noSmartTests ?? false,
     };
     // Initialize log writer if JSON logging enabled
+    // Default: enabled via settings (logJson: true), can be disabled with --no-log
     let logWriter = null;
-    if (mergedOptions.logJson && !config.dryRun) {
+    const shouldLog = !mergedOptions.noLog &&
+        !config.dryRun &&
+        (mergedOptions.logJson ?? settings.run.logJson);
+    if (shouldLog) {
         const runConfig = {
             phases: config.phases,
             sequential: config.sequential,
@@ -330,14 +762,19 @@ export async function runCommand(issues, options) {
             maxIterations: config.maxIterations,
         };
         logWriter = new LogWriter({
-            logPath: mergedOptions.logPath,
+            logPath: mergedOptions.logPath ?? settings.run.logPath,
             verbose: config.verbose,
         });
         await logWriter.initialize(runConfig);
     }
     // Display configuration
     console.log(chalk.gray(`  Stack: ${manifest.stack}`));
-    console.log(chalk.gray(`  Phases: ${config.phases.join(" → ")}`));
+    if (autoDetectPhases) {
+        console.log(chalk.gray(`  Phases: auto-detect from labels`));
+    }
+    else {
+        console.log(chalk.gray(`  Phases: ${config.phases.join(" → ")}`));
+    }
     console.log(chalk.gray(`  Mode: ${config.sequential ? "sequential" : "parallel"}`));
     if (config.qualityLoop) {
         console.log(chalk.gray(`  Quality loop: enabled (max ${config.maxIterations} iterations)`));
@@ -355,6 +792,25 @@ export async function runCommand(issues, options) {
         console.log(chalk.gray(`  Logging: JSON (run ${logWriter.getRunId()?.slice(0, 8)}...)`));
     }
     console.log(chalk.gray(`  Issues: ${issueNumbers.map((n) => `#${n}`).join(", ")}`));
+    // Worktree isolation is enabled by default for multi-issue runs
+    const useWorktreeIsolation = mergedOptions.worktreeIsolation !== false && issueNumbers.length > 0;
+    if (useWorktreeIsolation) {
+        console.log(chalk.gray(`  Worktree isolation: enabled`));
+    }
+    // Fetch issue info for all issues first
+    const issueInfoMap = new Map();
+    for (const issueNumber of issueNumbers) {
+        issueInfoMap.set(issueNumber, await getIssueInfo(issueNumber));
+    }
+    // Create worktrees for all issues before execution (if isolation enabled)
+    let worktreeMap = new Map();
+    if (useWorktreeIsolation && !config.dryRun) {
+        const issueData = issueNumbers.map((num) => ({
+            number: num,
+            title: issueInfoMap.get(num)?.title || `Issue #${num}`,
+        }));
+        worktreeMap = await ensureWorktrees(issueData, config.verbose, manifest.packageManager);
+    }
     // Execute
     const results = [];
     if (batches) {
@@ -362,7 +818,7 @@ export async function runCommand(issues, options) {
         for (let batchIdx = 0; batchIdx < batches.length; batchIdx++) {
             const batch = batches[batchIdx];
             console.log(chalk.blue(`\n  Batch ${batchIdx + 1}/${batches.length}: Issues ${batch.map((n) => `#${n}`).join(", ")}`));
-            const batchResults = await executeBatch(batch, config, logWriter, mergedOptions);
+            const batchResults = await executeBatch(batch, config, logWriter, mergedOptions, issueInfoMap, worktreeMap);
             results.push(...batchResults);
             // Check if batch failed and we should stop
             const batchFailed = batchResults.some((r) => !r.success);
@@ -375,12 +831,16 @@ export async function runCommand(issues, options) {
     else if (config.sequential) {
         // Sequential execution
         for (const issueNumber of issueNumbers) {
-            const issueInfo = await getIssueInfo(issueNumber);
+            const issueInfo = issueInfoMap.get(issueNumber) ?? {
+                title: `Issue #${issueNumber}`,
+                labels: [],
+            };
+            const worktreeInfo = worktreeMap.get(issueNumber);
             // Start issue logging
             if (logWriter) {
                 logWriter.startIssue(issueNumber, issueInfo.title, issueInfo.labels);
             }
-            const result = await runIssueWithLogging(issueNumber, config, logWriter, issueInfo.labels, mergedOptions);
+            const result = await runIssueWithLogging(issueNumber, config, logWriter, issueInfo.labels, mergedOptions, worktreeInfo?.path);
             results.push(result);
             // Complete issue logging
             if (logWriter) {
@@ -396,12 +856,16 @@ export async function runCommand(issues, options) {
         // Parallel execution (for now, just run sequentially but don't stop on failure)
         // TODO: Add proper parallel execution with listr2
         for (const issueNumber of issueNumbers) {
-            const issueInfo = await getIssueInfo(issueNumber);
+            const issueInfo = issueInfoMap.get(issueNumber) ?? {
+                title: `Issue #${issueNumber}`,
+                labels: [],
+            };
+            const worktreeInfo = worktreeMap.get(issueNumber);
             // Start issue logging
             if (logWriter) {
                 logWriter.startIssue(issueNumber, issueInfo.title, issueInfo.labels);
             }
-            const result = await runIssueWithLogging(issueNumber, config, logWriter, issueInfo.labels, mergedOptions);
+            const result = await runIssueWithLogging(issueNumber, config, logWriter, issueInfo.labels, mergedOptions, worktreeInfo?.path);
             results.push(result);
             // Complete issue logging
             if (logWriter) {
@@ -449,15 +913,19 @@ export async function runCommand(issues, options) {
 /**
  * Execute a batch of issues
  */
-async function executeBatch(issueNumbers, config, logWriter, options) {
+async function executeBatch(issueNumbers, config, logWriter, options, issueInfoMap, worktreeMap) {
     const results = [];
     for (const issueNumber of issueNumbers) {
-        const issueInfo = await getIssueInfo(issueNumber);
+        const issueInfo = issueInfoMap.get(issueNumber) ?? {
+            title: `Issue #${issueNumber}`,
+            labels: [],
+        };
+        const worktreeInfo = worktreeMap.get(issueNumber);
         // Start issue logging
         if (logWriter) {
             logWriter.startIssue(issueNumber, issueInfo.title, issueInfo.labels);
         }
-        const result = await runIssueWithLogging(issueNumber, config, logWriter, issueInfo.labels, options);
+        const result = await runIssueWithLogging(issueNumber, config, logWriter, issueInfo.labels, options, worktreeInfo?.path);
         results.push(result);
         // Complete issue logging
         if (logWriter) {
@@ -469,22 +937,113 @@ async function executeBatch(issueNumbers, config, logWriter, options) {
 /**
  * Execute all phases for a single issue with logging and quality loop
  */
-async function runIssueWithLogging(issueNumber, config, logWriter, labels, options) {
+async function runIssueWithLogging(issueNumber, config, logWriter, labels, options, worktreePath) {
     const startTime = Date.now();
     const phaseResults = [];
     let loopTriggered = false;
     let sessionId;
     console.log(chalk.blue(`\n  Issue #${issueNumber}`));
+    if (worktreePath) {
+        console.log(chalk.gray(`    Worktree: ${worktreePath}`));
+    }
     // Determine phases for this specific issue
-    const phases = determinePhasesForIssue(config.phases, labels, options);
-    if (phases.length !== config.phases.length) {
-        console.log(chalk.gray(`    Phases adjusted: ${phases.join(" → ")}`));
+    let phases;
+    let detectedQualityLoop = false;
+    let specAlreadyRan = false;
+    if (options.autoDetectPhases) {
+        // Check if labels indicate a simple bug/fix (skip spec entirely)
+        const lowerLabels = labels.map((l) => l.toLowerCase());
+        const isSimpleBugFix = lowerLabels.some((label) => BUG_LABELS.some((bugLabel) => label.includes(bugLabel)));
+        if (isSimpleBugFix) {
+            // Simple bug fix: skip spec, go straight to exec → qa
+            phases = ["exec", "qa"];
+            console.log(chalk.gray(`    Bug fix detected: ${phases.join(" → ")}`));
+        }
+        else {
+            // Run spec first to get recommended workflow
+            console.log(chalk.gray(`    Running spec to determine workflow...`));
+            console.log(chalk.gray(`    ⏳ spec...`));
+            const specStartTime = new Date();
+            // Note: spec runs in main repo (not worktree) for planning
+            const specResult = await executePhase(issueNumber, "spec", config, sessionId, worktreePath);
+            const specEndTime = new Date();
+            if (specResult.sessionId) {
+                sessionId = specResult.sessionId;
+            }
+            phaseResults.push(specResult);
+            specAlreadyRan = true;
+            // Log spec phase result
+            if (logWriter) {
+                const phaseLog = createPhaseLogFromTiming("spec", issueNumber, specStartTime, specEndTime, specResult.success
+                    ? "success"
+                    : specResult.error?.includes("Timeout")
+                        ? "timeout"
+                        : "failure", { error: specResult.error });
+                logWriter.logPhase(phaseLog);
+            }
+            if (!specResult.success) {
+                console.log(chalk.red(`    ✗ spec: ${specResult.error}`));
+                const durationSeconds = (Date.now() - startTime) / 1000;
+                return {
+                    issueNumber,
+                    success: false,
+                    phaseResults,
+                    durationSeconds,
+                    loopTriggered: false,
+                };
+            }
+            const duration = specResult.durationSeconds
+                ? ` (${formatDuration(specResult.durationSeconds)})`
+                : "";
+            console.log(chalk.green(`    ✓ spec${duration}`));
+            // Parse recommended workflow from spec output
+            let parsedWorkflow = specResult.output
+                ? parseRecommendedWorkflow(specResult.output)
+                : null;
+            if (parsedWorkflow) {
+                // Remove spec from phases since we already ran it
+                phases = parsedWorkflow.phases.filter((p) => p !== "spec");
+                detectedQualityLoop = parsedWorkflow.qualityLoop;
+                console.log(chalk.gray(`    Spec recommends: ${phases.join(" → ")}${detectedQualityLoop ? " (quality loop)" : ""}`));
+            }
+            else {
+                // Fall back to label-based detection
+                console.log(chalk.yellow(`    Could not parse spec recommendation, using label-based detection`));
+                const detected = detectPhasesFromLabels(labels);
+                phases = detected.phases.filter((p) => p !== "spec");
+                detectedQualityLoop = detected.qualityLoop;
+                console.log(chalk.gray(`    Fallback: ${phases.join(" → ")}`));
+            }
+        }
+    }
+    else {
+        // Use explicit phases with adjustments
+        phases = determinePhasesForIssue(config.phases, labels, options);
+        if (phases.length !== config.phases.length) {
+            console.log(chalk.gray(`    Phases adjusted: ${phases.join(" → ")}`));
+        }
+    }
+    // Add testgen phase if requested (and spec was in the phases)
+    if (options.testgen &&
+        (phases.includes("spec") || specAlreadyRan) &&
+        !phases.includes("testgen")) {
+        // Insert testgen at the beginning if spec already ran, otherwise after spec
+        if (specAlreadyRan) {
+            phases.unshift("testgen");
+        }
+        else {
+            const specIndex = phases.indexOf("spec");
+            if (specIndex !== -1) {
+                phases.splice(specIndex + 1, 0, "testgen");
+            }
+        }
     }
     let iteration = 0;
-    const maxIterations = config.qualityLoop ? config.maxIterations : 1;
+    const useQualityLoop = config.qualityLoop || detectedQualityLoop;
+    const maxIterations = useQualityLoop ? config.maxIterations : 1;
     while (iteration < maxIterations) {
         iteration++;
-        if (config.qualityLoop && iteration > 1) {
+        if (useQualityLoop && iteration > 1) {
             console.log(chalk.yellow(`    Quality loop iteration ${iteration}/${maxIterations}`));
             loopTriggered = true;
         }
@@ -492,7 +1051,7 @@ async function runIssueWithLogging(issueNumber, config, logWriter, labels, optio
         for (const phase of phases) {
             console.log(chalk.gray(`    ⏳ ${phase}...`));
             const phaseStartTime = new Date();
-            const result = await executePhase(issueNumber, phase, config, sessionId);
+            const result = await executePhase(issueNumber, phase, config, sessionId, worktreePath);
             const phaseEndTime = new Date();
             // Capture session ID for subsequent phases
             if (result.sessionId) {
@@ -518,9 +1077,9 @@ async function runIssueWithLogging(issueNumber, config, logWriter, labels, optio
                 console.log(chalk.red(`    ✗ ${phase}: ${result.error}`));
                 phasesFailed = true;
                 // If quality loop enabled, run loop phase to fix issues
-                if (config.qualityLoop && iteration < maxIterations) {
+                if (useQualityLoop && iteration < maxIterations) {
                     console.log(chalk.yellow(`    Running /loop to fix issues...`));
-                    const loopResult = await executePhase(issueNumber, "loop", config, sessionId);
+                    const loopResult = await executePhase(issueNumber, "loop", config, sessionId, worktreePath);
                     phaseResults.push(loopResult);
                     if (loopResult.sessionId) {
                         sessionId = loopResult.sessionId;