sequant 1.9.0 → 1.10.1

package/README.md

@@ -84,6 +84,7 @@ Run without Claude Code UI:
 npx sequant run 123              # Single issue
 npx sequant run 1 2 3            # Batch (parallel)
 npx sequant run 123 --quality-loop
+npx sequant run 123 --base feature/dashboard  # Custom base branch
 ```
 
 ---
@@ -148,7 +149,8 @@ See [Run Command Options](docs/run-command.md) for advanced usage.
 {
   "run": {
     "qualityLoop": false,
-    "maxIterations": 3
+    "maxIterations": 3,
+    "defaultBase": "feature/dashboard"  // Optional: custom default base branch
   }
 }
 ```
@@ -173,6 +175,7 @@ See [Customization Guide](docs/customization.md) for all options.
 - [Getting Started](docs/getting-started/installation.md)
 - [Workflow Concepts](docs/concepts/workflow-phases.md)
 - [Run Command](docs/run-command.md)
+- [Feature Branch Workflows](docs/feature-branch-workflow.md)
 - [Customization](docs/customization.md)
 - [Troubleshooting](docs/troubleshooting.md)
 

package/dist/bin/cli.js

@@ -99,6 +99,7 @@ program
     .option("--testgen", "Run testgen phase after spec")
     .option("--quiet", "Suppress version warnings and non-essential output")
     .option("--chain", "Chain issues: each branches from previous (requires --sequential)")
+    .option("--base <branch>", "Base branch for worktree creation (default: main or settings.run.defaultBase)")
     .action(runCommand);
 program
     .command("logs")

package/dist/src/commands/run.d.ts

@@ -66,6 +66,11 @@ interface RunOptions {
     quiet?: boolean;
     /** Chain issues: each branches from previous (requires --sequential) */
     chain?: boolean;
+    /**
+     * Base branch for worktree creation.
+     * Resolution priority: this CLI flag → settings.run.defaultBase → 'main'
+     */
+    base?: string;
 }
 /**
  * Main run command

package/dist/src/commands/run.js

@@ -13,6 +13,7 @@ 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 { StateManager, } from "../lib/workflow/state-manager.js";
 import { DEFAULT_PHASES, DEFAULT_CONFIG, } from "../lib/workflow/types.js";
 import { ShutdownManager } from "../lib/shutdown.js";
 import { checkVersionCached, getVersionWarning } from "../lib/version-check.js";
@@ -106,8 +107,9 @@ export function getWorktreeChangedFiles(worktreePath) {
 /**
  * Create or reuse a worktree for an issue
  * @param baseBranch - Optional branch to use as base instead of origin/main (for chain mode)
+ * @param chainMode - If true and branch exists, rebase onto baseBranch instead of using as-is
  */
-async function ensureWorktree(issueNumber, title, verbose, packageManager, baseBranch) {
+async function ensureWorktree(issueNumber, title, verbose, packageManager, baseBranch, chainMode) {
     const gitRoot = getGitRoot();
     if (!gitRoot) {
         console.log(chalk.red("    ❌ Not in a git repository"));
@@ -128,6 +130,7 @@ async function ensureWorktree(issueNumber, title, verbose, packageManager, baseB
             path: existingPath,
             branch,
             existed: true,
+            rebased: false,
         };
     }
     // Check if branch exists (but no worktree)
@@ -137,17 +140,29 @@ async function ensureWorktree(issueNumber, title, verbose, packageManager, baseB
         console.log(chalk.gray(`    🌿 Creating worktree for #${issueNumber}...`));
     }
     // Determine the base for the new branch
-    const baseRef = baseBranch || "origin/main";
-    // Fetch latest main to ensure worktree starts from fresh baseline (unless using local branch)
-    if (!baseBranch) {
+    // For custom base branches, use origin/<branch> if it's a remote-style reference
+    // For local branches (chain mode), use as-is
+    const isLocalBranch = baseBranch && !baseBranch.startsWith("origin/") && baseBranch !== "main";
+    const baseRef = baseBranch
+        ? isLocalBranch
+            ? baseBranch
+            : baseBranch.startsWith("origin/")
+                ? baseBranch
+                : `origin/${baseBranch}`
+        : "origin/main";
+    // Fetch the base branch to ensure worktree starts from fresh baseline
+    const branchToFetch = baseBranch
+        ? baseBranch.replace(/^origin\//, "")
+        : "main";
+    if (!isLocalBranch) {
         if (verbose) {
-            console.log(chalk.gray(`    🔄 Fetching latest main...`));
+            console.log(chalk.gray(`    🔄 Fetching latest ${branchToFetch}...`));
         }
-        const fetchResult = spawnSync("git", ["fetch", "origin", "main"], {
+        const fetchResult = spawnSync("git", ["fetch", "origin", branchToFetch], {
             stdio: "pipe",
         });
         if (fetchResult.status !== 0 && verbose) {
-            console.log(chalk.yellow(`    ⚠️  Could not fetch origin/main, using local state`));
+            console.log(chalk.yellow(`    ⚠️  Could not fetch origin/${branchToFetch}, using local state`));
         }
     }
     else if (verbose) {
@@ -159,11 +174,16 @@ async function ensureWorktree(issueNumber, title, verbose, packageManager, baseB
     }
     // Create the worktree
     let createResult;
+    let needsRebase = false;
     if (branchExists) {
         // Use existing branch
         createResult = spawnSync("git", ["worktree", "add", worktreePath, branch], {
             stdio: "pipe",
         });
+        // In chain mode with existing branch, mark for rebase onto previous chain link
+        if (chainMode && baseBranch) {
+            needsRebase = true;
+        }
     }
     else {
         // Create new branch from base reference (origin/main or previous branch in chain)
@@ -174,6 +194,39 @@ async function ensureWorktree(issueNumber, title, verbose, packageManager, baseB
         console.log(chalk.red(`    ❌ Failed to create worktree: ${error}`));
         return null;
     }
+    // Rebase existing branch onto chain base if needed
+    let rebased = false;
+    if (needsRebase) {
+        if (verbose) {
+            console.log(chalk.gray(`    🔄 Rebasing existing branch onto previous chain link (${baseRef})...`));
+        }
+        const rebaseResult = spawnSync("git", ["-C", worktreePath, "rebase", baseRef], {
+            stdio: "pipe",
+        });
+        if (rebaseResult.status !== 0) {
+            const rebaseError = rebaseResult.stderr.toString();
+            // Check if it's a conflict
+            if (rebaseError.includes("CONFLICT") ||
+                rebaseError.includes("could not apply")) {
+                console.log(chalk.yellow(`    ⚠️  Rebase conflict detected. Aborting rebase and keeping original branch state.`));
+                console.log(chalk.yellow(`    ℹ️  Branch ${branch} is not properly chained. Manual rebase may be required.`));
+                // Abort the rebase to restore branch state
+                spawnSync("git", ["-C", worktreePath, "rebase", "--abort"], {
+                    stdio: "pipe",
+                });
+            }
+            else {
+                console.log(chalk.yellow(`    ⚠️  Rebase failed: ${rebaseError.trim()}`));
+                console.log(chalk.yellow(`    ℹ️  Continuing with branch in its original state.`));
+            }
+        }
+        else {
+            rebased = true;
+            if (verbose) {
+                console.log(chalk.green(`    ✅ Branch rebased onto ${baseRef}`));
+            }
+        }
+    }
     // Copy .env.local if it exists
     const envLocalSrc = path.join(gitRoot, ".env.local");
     const envLocalDst = path.join(worktreePath, ".env.local");
@@ -212,16 +265,19 @@ async function ensureWorktree(issueNumber, title, verbose, packageManager, baseB
         path: worktreePath,
         branch,
         existed: false,
+        rebased,
     };
 }
 /**
  * Ensure worktrees exist for all issues before execution
+ * @param baseBranch - Optional base branch for worktree creation (default: main)
  */
-async function ensureWorktrees(issues, verbose, packageManager) {
+async function ensureWorktrees(issues, verbose, packageManager, baseBranch) {
     const worktrees = new Map();
-    console.log(chalk.blue("\n  📂 Preparing worktrees..."));
+    const baseDisplay = baseBranch || "main";
+    console.log(chalk.blue(`\n  📂 Preparing worktrees from ${baseDisplay}...`));
     for (const issue of issues) {
-        const worktree = await ensureWorktree(issue.number, issue.title, verbose, packageManager);
+        const worktree = await ensureWorktree(issue.number, issue.title, verbose, packageManager, baseBranch, false);
         if (worktree) {
             worktrees.set(issue.number, worktree);
         }
@@ -236,13 +292,17 @@ async function ensureWorktrees(issues, verbose, packageManager) {
 /**
  * Ensure worktrees exist for all issues in chain mode
  * Each issue branches from the previous issue's branch
+ * @param baseBranch - Optional starting base branch for the chain (default: main)
  */
-async function ensureWorktreesChain(issues, verbose, packageManager) {
+async function ensureWorktreesChain(issues, verbose, packageManager, baseBranch) {
     const worktrees = new Map();
-    console.log(chalk.blue("\n  🔗 Preparing chained worktrees..."));
-    let previousBranch;
+    const baseDisplay = baseBranch || "main";
+    console.log(chalk.blue(`\n  🔗 Preparing chained worktrees from ${baseDisplay}...`));
+    // First issue starts from the specified base branch (or main)
+    let previousBranch = baseBranch;
     for (const issue of issues) {
-        const worktree = await ensureWorktree(issue.number, issue.title, verbose, packageManager, previousBranch);
+        const worktree = await ensureWorktree(issue.number, issue.title, verbose, packageManager, previousBranch, // Chain from previous branch (or base branch for first issue)
+        true);
         if (worktree) {
             worktrees.set(issue.number, worktree);
             previousBranch = worktree.branch; // Next issue will branch from this
@@ -255,8 +315,13 @@ async function ensureWorktreesChain(issues, verbose, packageManager) {
     }
     const created = Array.from(worktrees.values()).filter((w) => !w.existed).length;
     const reused = Array.from(worktrees.values()).filter((w) => w.existed).length;
+    const rebased = Array.from(worktrees.values()).filter((w) => w.rebased).length;
     if (created > 0 || reused > 0) {
-        console.log(chalk.gray(`  Chained worktrees: ${created} created, ${reused} reused`));
+        let msg = `  Chained worktrees: ${created} created, ${reused} reused`;
+        if (rebased > 0) {
+            msg += `, ${rebased} rebased`;
+        }
+        console.log(chalk.gray(msg));
     }
     // Show chain structure
     if (worktrees.size > 0) {
@@ -264,7 +329,7 @@ async function ensureWorktreesChain(issues, verbose, packageManager) {
             .filter((i) => worktrees.has(i.number))
             .map((i) => `#${i.number}`)
             .join(" → ");
-        console.log(chalk.gray(`  Chain: origin/main → ${chainOrder}`));
+        console.log(chalk.gray(`  Chain: ${baseDisplay} → ${chainOrder}`));
     }
     return worktrees;
 }
@@ -869,6 +934,8 @@ export async function runCommand(issues, options) {
     // Determine if we should auto-detect phases from labels
     const autoDetectPhases = !options.phases && settings.run.autoDetectPhases;
     mergedOptions.autoDetectPhases = autoDetectPhases;
+    // Resolve base branch: CLI flag → settings.run.defaultBase → 'main'
+    const resolvedBaseBranch = options.base ?? settings.run.defaultBase ?? undefined;
     // Parse issue numbers (or use batch mode)
     let issueNumbers;
     let batches = null;
@@ -953,6 +1020,12 @@ export async function runCommand(issues, options) {
         });
         await logWriter.initialize(runConfig);
     }
+    // Initialize state manager for persistent workflow state tracking
+    // State tracking is always enabled (unless dry run)
+    let stateManager = null;
+    if (!config.dryRun) {
+        stateManager = new StateManager({ verbose: config.verbose });
+    }
     // Initialize shutdown manager for graceful interruption handling
     const shutdown = new ShutdownManager();
     // Register log writer finalization as cleanup task
@@ -986,12 +1059,18 @@ export async function runCommand(issues, options) {
     if (logWriter) {
         console.log(chalk.gray(`  Logging: JSON (run ${logWriter.getRunId()?.slice(0, 8)}...)`));
     }
+    if (stateManager) {
+        console.log(chalk.gray(`  State tracking: enabled`));
+    }
     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`));
     }
+    if (resolvedBaseBranch) {
+        console.log(chalk.gray(`  Base branch: ${resolvedBaseBranch}`));
+    }
     if (mergedOptions.chain) {
         console.log(chalk.gray(`  Chain mode: enabled (each issue branches from previous)`));
     }
@@ -1009,10 +1088,10 @@ export async function runCommand(issues, options) {
         }));
         // Use chain mode or standard worktree creation
         if (mergedOptions.chain) {
-            worktreeMap = await ensureWorktreesChain(issueData, config.verbose, manifest.packageManager);
+            worktreeMap = await ensureWorktreesChain(issueData, config.verbose, manifest.packageManager, resolvedBaseBranch);
         }
         else {
-            worktreeMap = await ensureWorktrees(issueData, config.verbose, manifest.packageManager);
+            worktreeMap = await ensureWorktrees(issueData, config.verbose, manifest.packageManager, resolvedBaseBranch);
         }
         // Register cleanup tasks for newly created worktrees (not pre-existing ones)
         for (const [issueNum, worktree] of worktreeMap.entries()) {
@@ -1038,7 +1117,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, issueInfoMap, worktreeMap, shutdown);
+                const batchResults = await executeBatch(batch, config, logWriter, stateManager, mergedOptions, issueInfoMap, worktreeMap, shutdown);
                 results.push(...batchResults);
                 // Check if batch failed and we should stop
                 const batchFailed = batchResults.some((r) => !r.success);
@@ -1060,7 +1139,7 @@ export async function runCommand(issues, options) {
                 if (logWriter) {
                     logWriter.startIssue(issueNumber, issueInfo.title, issueInfo.labels);
                 }
-                const result = await runIssueWithLogging(issueNumber, config, logWriter, issueInfo.labels, mergedOptions, worktreeInfo?.path, shutdown, mergedOptions.chain);
+                const result = await runIssueWithLogging(issueNumber, config, logWriter, stateManager, issueInfo.title, issueInfo.labels, mergedOptions, worktreeInfo?.path, worktreeInfo?.branch, shutdown, mergedOptions.chain);
                 results.push(result);
                 // Complete issue logging
                 if (logWriter) {
@@ -1094,7 +1173,7 @@ export async function runCommand(issues, options) {
                 if (logWriter) {
                     logWriter.startIssue(issueNumber, issueInfo.title, issueInfo.labels);
                 }
-                const result = await runIssueWithLogging(issueNumber, config, logWriter, issueInfo.labels, mergedOptions, worktreeInfo?.path, shutdown, false);
+                const result = await runIssueWithLogging(issueNumber, config, logWriter, stateManager, issueInfo.title, issueInfo.labels, mergedOptions, worktreeInfo?.path, worktreeInfo?.branch, shutdown, false);
                 results.push(result);
                 // Complete issue logging
                 if (logWriter) {
@@ -1151,7 +1230,7 @@ export async function runCommand(issues, options) {
 /**
  * Execute a batch of issues
  */
-async function executeBatch(issueNumbers, config, logWriter, options, issueInfoMap, worktreeMap, shutdownManager) {
+async function executeBatch(issueNumbers, config, logWriter, stateManager, options, issueInfoMap, worktreeMap, shutdownManager) {
     const results = [];
     for (const issueNumber of issueNumbers) {
         // Check if shutdown was triggered
@@ -1167,7 +1246,7 @@ async function executeBatch(issueNumbers, config, logWriter, options, issueInfoM
         if (logWriter) {
             logWriter.startIssue(issueNumber, issueInfo.title, issueInfo.labels);
         }
-        const result = await runIssueWithLogging(issueNumber, config, logWriter, issueInfo.labels, options, worktreeInfo?.path, shutdownManager, false);
+        const result = await runIssueWithLogging(issueNumber, config, logWriter, stateManager, issueInfo.title, issueInfo.labels, options, worktreeInfo?.path, worktreeInfo?.branch, shutdownManager, false);
         results.push(result);
         // Complete issue logging
         if (logWriter) {
@@ -1179,7 +1258,7 @@ async function executeBatch(issueNumbers, config, logWriter, options, issueInfoM
 /**
  * Execute all phases for a single issue with logging and quality loop
  */
-async function runIssueWithLogging(issueNumber, config, logWriter, labels, options, worktreePath, shutdownManager, chainMode) {
+async function runIssueWithLogging(issueNumber, config, logWriter, stateManager, issueTitle, labels, options, worktreePath, branch, shutdownManager, chainMode) {
     const startTime = Date.now();
     const phaseResults = [];
     let loopTriggered = false;
@@ -1188,6 +1267,32 @@ async function runIssueWithLogging(issueNumber, config, logWriter, labels, optio
     if (worktreePath) {
         console.log(chalk.gray(`    Worktree: ${worktreePath}`));
     }
+    // Initialize state tracking for this issue
+    if (stateManager) {
+        try {
+            const existingState = await stateManager.getIssueState(issueNumber);
+            if (!existingState) {
+                await stateManager.initializeIssue(issueNumber, issueTitle, {
+                    worktree: worktreePath,
+                    branch,
+                    qualityLoop: config.qualityLoop,
+                    maxIterations: config.maxIterations,
+                });
+            }
+            else {
+                // Update worktree info if it changed
+                if (worktreePath && branch) {
+                    await stateManager.updateWorktreeInfo(issueNumber, worktreePath, branch);
+                }
+            }
+        }
+        catch (error) {
+            // State tracking errors shouldn't stop execution
+            if (config.verbose) {
+                console.log(chalk.yellow(`    ⚠️  State tracking error: ${error}`));
+            }
+        }
+    }
     // Determine phases for this specific issue
     let phases;
     let detectedQualityLoop = false;
@@ -1205,6 +1310,15 @@ async function runIssueWithLogging(issueNumber, config, logWriter, labels, optio
             // Run spec first to get recommended workflow
             console.log(chalk.gray(`    Running spec to determine workflow...`));
             console.log(chalk.gray(`    ⏳ spec...`));
+            // Track spec phase start in state
+            if (stateManager) {
+                try {
+                    await stateManager.updatePhaseStatus(issueNumber, "spec", "in_progress");
+                }
+                catch {
+                    // State tracking errors shouldn't stop execution
+                }
+            }
             const specStartTime = new Date();
             // Note: spec runs in main repo (not worktree) for planning
             const specResult = await executePhase(issueNumber, "spec", config, sessionId, worktreePath, // Will be ignored for spec (non-isolated phase)
@@ -1212,6 +1326,15 @@ async function runIssueWithLogging(issueNumber, config, logWriter, labels, optio
             const specEndTime = new Date();
             if (specResult.sessionId) {
                 sessionId = specResult.sessionId;
+                // Update session ID in state for resume capability
+                if (stateManager) {
+                    try {
+                        await stateManager.updateSessionId(issueNumber, specResult.sessionId);
+                    }
+                    catch {
+                        // State tracking errors shouldn't stop execution
+                    }
+                }
             }
             phaseResults.push(specResult);
             specAlreadyRan = true;
@@ -1224,6 +1347,18 @@ async function runIssueWithLogging(issueNumber, config, logWriter, labels, optio
                         : "failure", { error: specResult.error });
                 logWriter.logPhase(phaseLog);
             }
+            // Track spec phase completion in state
+            if (stateManager) {
+                try {
+                    const phaseStatus = specResult.success ? "completed" : "failed";
+                    await stateManager.updatePhaseStatus(issueNumber, "spec", phaseStatus, {
+                        error: specResult.error,
+                    });
+                }
+                catch {
+                    // State tracking errors shouldn't stop execution
+                }
+            }
             if (!specResult.success) {
                 console.log(chalk.red(`    ✗ spec: ${specResult.error}`));
                 const durationSeconds = (Date.now() - startTime) / 1000;
@@ -1294,12 +1429,30 @@ async function runIssueWithLogging(issueNumber, config, logWriter, labels, optio
         let phasesFailed = false;
         for (const phase of phases) {
             console.log(chalk.gray(`    ⏳ ${phase}...`));
+            // Track phase start in state
+            if (stateManager) {
+                try {
+                    await stateManager.updatePhaseStatus(issueNumber, phase, "in_progress");
+                }
+                catch {
+                    // State tracking errors shouldn't stop execution
+                }
+            }
             const phaseStartTime = new Date();
             const result = await executePhase(issueNumber, phase, config, sessionId, worktreePath, shutdownManager);
             const phaseEndTime = new Date();
             // Capture session ID for subsequent phases
             if (result.sessionId) {
                 sessionId = result.sessionId;
+                // Update session ID in state for resume capability
+                if (stateManager) {
+                    try {
+                        await stateManager.updateSessionId(issueNumber, result.sessionId);
+                    }
+                    catch {
+                        // State tracking errors shouldn't stop execution
+                    }
+                }
             }
             phaseResults.push(result);
             // Log phase result
@@ -1311,6 +1464,20 @@ async function runIssueWithLogging(issueNumber, config, logWriter, labels, optio
                         : "failure", { error: result.error });
                 logWriter.logPhase(phaseLog);
             }
+            // Track phase completion in state
+            if (stateManager) {
+                try {
+                    const phaseStatus = result.success
+                        ? "completed"
+                        : result.error?.includes("Timeout")
+                            ? "failed"
+                            : "failed";
+                    await stateManager.updatePhaseStatus(issueNumber, phase, phaseStatus, { error: result.error });
+                }
+                catch {
+                    // State tracking errors shouldn't stop execution
+                }
+            }
             if (result.success) {
                 const duration = result.durationSeconds
                     ? ` (${formatDuration(result.durationSeconds)})`
@@ -1355,6 +1522,16 @@ async function runIssueWithLogging(issueNumber, config, logWriter, labels, optio
     // Success is determined by whether all phases completed in any iteration,
     // not whether all accumulated phase results passed (which would fail after loop recovery)
     const success = completedSuccessfully;
+    // Update final issue status in state
+    if (stateManager) {
+        try {
+            const finalStatus = success ? "ready_for_merge" : "in_progress";
+            await stateManager.updateIssueStatus(issueNumber, finalStatus);
+        }
+        catch {
+            // State tracking errors shouldn't stop execution
+        }
+    }
     // Create checkpoint commit in chain mode after QA passes
     if (success && chainMode && worktreePath) {
         createCheckpointCommit(worktreePath, issueNumber, config.verbose);

package/dist/src/commands/status.d.ts

@@ -1,4 +1,20 @@
 /**
- * sequant status - Show version and configuration
+ * sequant status - Show version, configuration, and workflow state
  */
-export declare function statusCommand(): Promise<void>;
+export interface StatusCommandOptions {
+    /** Show only issues state */
+    issues?: boolean;
+    /** Show details for a specific issue */
+    issue?: number;
+    /** Output as JSON */
+    json?: boolean;
+    /** Rebuild state from run logs */
+    rebuild?: boolean;
+    /** Clean up stale/orphaned entries */
+    cleanup?: boolean;
+    /** Only show what would be cleaned (used with --cleanup) */
+    dryRun?: boolean;
+    /** Remove entries older than this many days (used with --cleanup) */
+    maxAge?: number;
+}
+export declare function statusCommand(options?: StatusCommandOptions): Promise<void>;