sequant 1.10.1 → 1.12.0

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

@@ -0,0 +1,25 @@
+/**
+ * sequant dashboard - Visual workflow state dashboard
+ *
+ * Starts a local web server displaying workflow state in a browser-based
+ * dashboard with live updates via SSE.
+ *
+ * @example
+ * ```bash
+ * sequant dashboard           # Start on default port 3456
+ * sequant dashboard --port 8080  # Custom port
+ * sequant dashboard --no-open    # Don't auto-open browser
+ * ```
+ */
+export interface DashboardCommandOptions {
+    /** Port to run the server on */
+    port?: number;
+    /** Don't automatically open browser */
+    noOpen?: boolean;
+    /** Enable verbose logging */
+    verbose?: boolean;
+}
+/**
+ * Dashboard command handler
+ */
+export declare function dashboardCommand(options?: DashboardCommandOptions): Promise<void>;

package/dist/src/commands/dashboard.js

@@ -0,0 +1,44 @@
+/**
+ * sequant dashboard - Visual workflow state dashboard
+ *
+ * Starts a local web server displaying workflow state in a browser-based
+ * dashboard with live updates via SSE.
+ *
+ * @example
+ * ```bash
+ * sequant dashboard           # Start on default port 3456
+ * sequant dashboard --port 8080  # Custom port
+ * sequant dashboard --no-open    # Don't auto-open browser
+ * ```
+ */
+import chalk from "chalk";
+/**
+ * Dashboard command handler
+ */
+export async function dashboardCommand(options = {}) {
+    const port = options.port ?? 3456;
+    const shouldOpen = !options.noOpen;
+    const verbose = options.verbose ?? false;
+    console.log(chalk.bold("\n📊 Sequant Dashboard\n"));
+    try {
+        // Dynamic import to avoid loading dashboard code unless needed
+        const { startDashboard } = await import("../../dashboard/server.js");
+        const server = await startDashboard({
+            port,
+            open: shouldOpen,
+            verbose,
+        });
+        // Handle graceful shutdown
+        const shutdown = () => {
+            server.close();
+            process.exit(0);
+        };
+        process.on("SIGINT", shutdown);
+        process.on("SIGTERM", shutdown);
+        console.log(chalk.gray("Press Ctrl+C to stop the server\n"));
+    }
+    catch (error) {
+        console.error(chalk.red(`\n✗ Failed to start dashboard: ${error}\n`));
+        process.exit(1);
+    }
+}

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

@@ -1,4 +1,21 @@
 /**
  * sequant doctor - Check installation health
  */
-export declare function doctorCommand(): Promise<void>;
+export interface DoctorOptions {
+    skipIssueCheck?: boolean;
+}
+interface ClosedIssue {
+    number: number;
+    title: string;
+    closedAt: string;
+    labels: Array<{
+        name: string;
+    }>;
+}
+/**
+ * Check recently closed issues for missing commits in main branch
+ * Returns issues that were closed but have no commit referencing them
+ */
+export declare function checkClosedIssues(): ClosedIssue[];
+export declare function doctorCommand(options?: DoctorOptions): Promise<void>;
+export {};

package/dist/src/commands/doctor.js

@@ -2,13 +2,76 @@
  * sequant doctor - Check installation health
  */
 import chalk from "chalk";
+import { execSync } from "child_process";
 import { fileExists, isExecutable } from "../lib/fs.js";
 import { getManifest } from "../lib/manifest.js";
-import { commandExists, isGhAuthenticated, isNativeWindows, isWSL, checkOptionalMcpServers, OPTIONAL_MCP_SERVERS, } from "../lib/system.js";
+import { commandExists, isGhAuthenticated, isNativeWindows, isWSL, checkOptionalMcpServers, getMcpServersConfig, OPTIONAL_MCP_SERVERS, } from "../lib/system.js";
 import { checkVersionThorough, getVersionWarning, } from "../lib/version-check.js";
-export async function doctorCommand() {
+/**
+ * Labels that indicate an issue should be skipped from closed-issue verification
+ * (case-insensitive matching)
+ */
+const SKIP_ISSUE_LABELS = [
+    "wontfix",
+    "won't fix",
+    "duplicate",
+    "invalid",
+    "question",
+    "documentation",
+    "docs",
+];
+/**
+ * Check recently closed issues for missing commits in main branch
+ * Returns issues that were closed but have no commit referencing them
+ */
+export function checkClosedIssues() {
+    const sevenDaysAgo = new Date();
+    sevenDaysAgo.setDate(sevenDaysAgo.getDate() - 7);
+    const sevenDaysAgoISO = sevenDaysAgo.toISOString();
+    // Fetch closed issues from last 7 days
+    let closedIssues;
+    try {
+        const output = execSync(`gh issue list --state closed --json number,title,closedAt,labels --limit 100`, { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] });
+        closedIssues = JSON.parse(output);
+    }
+    catch {
+        // gh command failed - return empty (graceful degradation)
+        return [];
+    }
+    // Filter to last 7 days
+    const recentIssues = closedIssues.filter((issue) => issue.closedAt >= sevenDaysAgoISO);
+    // Filter out issues with skip labels
+    const issuesToCheck = recentIssues.filter((issue) => {
+        const labels = issue.labels.map((l) => l.name.toLowerCase());
+        return !SKIP_ISSUE_LABELS.some((skipLabel) => labels.some((label) => label.includes(skipLabel.toLowerCase())));
+    });
+    // Check each issue for a commit in main
+    const missingCommitIssues = [];
+    for (const issue of issuesToCheck) {
+        try {
+            // Look for commit mentioning this issue number
+            const result = execSync(`git log --oneline --grep="#${issue.number}" -1`, {
+                encoding: "utf-8",
+                stdio: ["pipe", "pipe", "pipe"],
+            });
+            // If no output, no commit found
+            if (!result.trim()) {
+                missingCommitIssues.push(issue);
+            }
+        }
+        catch {
+            // git log failed or no match - treat as missing
+            missingCommitIssues.push(issue);
+        }
+    }
+    return missingCommitIssues;
+}
+export async function doctorCommand(options = {}) {
     console.log(chalk.blue("\n🔍 Running health checks...\n"));
     const checks = [];
+    // Track gh availability and auth for conditional checks later
+    let ghAvailable = false;
+    let ghAuthenticated = false;
     // Check 0: Version freshness
     const versionResult = await checkVersionThorough();
     if (versionResult.latestVersion) {
@@ -160,6 +223,7 @@ export async function doctorCommand() {
     }
     // Check 8: GitHub CLI installed
     if (commandExists("gh")) {
+        ghAvailable = true;
         checks.push({
             name: "GitHub CLI",
             status: "pass",
@@ -167,6 +231,7 @@ export async function doctorCommand() {
         });
         // Check 9: GitHub CLI authenticated (only if gh exists)
         if (isGhAuthenticated()) {
+            ghAuthenticated = true;
             checks.push({
                 name: "GitHub Auth",
                 status: "pass",
@@ -266,6 +331,44 @@ export async function doctorCommand() {
             message: "No optional MCPs configured (Sequant works without them, but they enhance functionality)",
         });
     }
+    // Check: MCP availability for headless mode (sequant run)
+    const mcpServersConfig = getMcpServersConfig();
+    if (mcpServersConfig) {
+        const serverCount = Object.keys(mcpServersConfig).length;
+        checks.push({
+            name: "MCP Servers (headless)",
+            status: "pass",
+            message: `Available for sequant run (${serverCount} server${serverCount !== 1 ? "s" : ""} configured)`,
+        });
+    }
+    else {
+        checks.push({
+            name: "MCP Servers (headless)",
+            status: "warn",
+            message: "Not available for sequant run (no Claude Desktop config found or empty mcpServers)",
+        });
+    }
+    // Check: Closed issue verification (only if gh available, authenticated, and not skipped)
+    if (!options.skipIssueCheck && ghAvailable && ghAuthenticated && gitExists) {
+        const missingCommitIssues = checkClosedIssues();
+        if (missingCommitIssues.length === 0) {
+            checks.push({
+                name: "Closed Issues",
+                status: "pass",
+                message: "All recently closed issues have commits in main",
+            });
+        }
+        else {
+            // Add a warning for each issue missing commits
+            for (const issue of missingCommitIssues) {
+                checks.push({
+                    name: `Issue #${issue.number}`,
+                    status: "warn",
+                    message: `Closed but no commit found in main: "${issue.title}"`,
+                });
+            }
+        }
+    }
     // Display results
     let passCount = 0;
     let warnCount = 0;

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

@@ -7,6 +7,7 @@ interface InitOptions {
     force?: boolean;
     interactive?: boolean;
     skipSetup?: boolean;
+    noSymlinks?: boolean;
 }
 export declare function initCommand(options: InitOptions): Promise<void>;
 export {};

package/dist/src/commands/init.js

@@ -266,9 +266,33 @@ export async function initCommand(options) {
     // Create default settings
     console.log(chalk.blue("⚙️  Creating default settings..."));
     await createDefaultSettings();
-    // Copy templates
+    // Copy templates (with symlinks for scripts unless --no-symlinks)
     console.log(chalk.blue("📄 Copying templates..."));
-    await copyTemplates(stack, tokens);
+    const { scriptsSymlinked, symlinkResults } = await copyTemplates(stack, tokens, {
+        noSymlinks: options.noSymlinks,
+        force: options.force,
+    });
+    // Report symlink status
+    if (scriptsSymlinked) {
+        console.log(chalk.blue("🔗 Created symlinks for scripts/dev/"));
+    }
+    else if (!options.noSymlinks && symlinkResults) {
+        // Some symlinks may have fallen back to copies
+        const fallbacks = symlinkResults.filter((r) => r.fallbackToCopy);
+        if (fallbacks.length > 0) {
+            console.log(chalk.yellow("⚠️  Some scripts were copied instead of symlinked:"));
+            for (const fb of fallbacks) {
+                console.log(chalk.gray(`   ${fb.path}: ${fb.reason}`));
+            }
+        }
+        const skipped = symlinkResults.filter((r) => r.skipped);
+        if (skipped.length > 0) {
+            console.log(chalk.yellow("⚠️  Some scripts were skipped (existing files found):"));
+            for (const s of skipped) {
+                console.log(chalk.gray(`   ${s.path}: ${s.reason}`));
+            }
+        }
+    }
     // Create manifest
     console.log(chalk.blue("📋 Creating manifest..."));
     await createManifest(stack, packageManager ?? undefined);

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

@@ -17,6 +17,14 @@ export declare function listWorktrees(): Array<{
  * Get changed files in a worktree compared to main
  */
 export declare function getWorktreeChangedFiles(worktreePath: string): string[];
+/**
+ * Get diff stats for a worktree (files changed, lines added)
+ * Returns aggregate metrics only - no file paths to preserve privacy
+ */
+export declare function getWorktreeDiffStats(worktreePath: string): {
+    filesChanged: number;
+    linesAdded: number;
+};
 /**
  * Create a checkpoint commit in the worktree after QA passes
  * This allows recovery in case later issues in the chain fail
@@ -66,11 +74,23 @@ interface RunOptions {
     quiet?: boolean;
     /** Chain issues: each branches from previous (requires --sequential) */
     chain?: boolean;
+    /**
+     * Wait for QA pass before starting next issue in chain mode.
+     * When enabled, the chain pauses if QA fails, preventing downstream issues
+     * from building on potentially broken code.
+     */
+    qaGate?: boolean;
     /**
      * Base branch for worktree creation.
      * Resolution priority: this CLI flag → settings.run.defaultBase → 'main'
      */
     base?: string;
+    /**
+     * Disable MCP servers in headless mode.
+     * When true, MCPs are not passed to the SDK (faster/cheaper runs).
+     * Resolution priority: this CLI flag → settings.run.mcp → default (true)
+     */
+    noMcp?: boolean;
 }
 /**
  * Main run command

package/dist/src/commands/run.js

@@ -13,10 +13,13 @@ 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 { StateManager } from "../lib/workflow/state-manager.js";
 import { DEFAULT_PHASES, DEFAULT_CONFIG, } from "../lib/workflow/types.js";
 import { ShutdownManager } from "../lib/shutdown.js";
+import { getMcpServersConfig } from "../lib/system.js";
 import { checkVersionCached, getVersionWarning } from "../lib/version-check.js";
+import { MetricsWriter } from "../lib/workflow/metrics-writer.js";
+import { determineOutcome, } from "../lib/workflow/metrics-schema.js";
 /**
  * Slugify a title for branch naming
  */
@@ -104,6 +107,29 @@ export function getWorktreeChangedFiles(worktreePath) {
         .split("\n")
         .filter((f) => f.length > 0);
 }
+/**
+ * Get diff stats for a worktree (files changed, lines added)
+ * Returns aggregate metrics only - no file paths to preserve privacy
+ */
+export function getWorktreeDiffStats(worktreePath) {
+    const result = spawnSync("git", ["-C", worktreePath, "diff", "--stat", "main...HEAD"], { stdio: "pipe" });
+    if (result.status !== 0) {
+        return { filesChanged: 0, linesAdded: 0 };
+    }
+    const output = result.stdout.toString();
+    const lines = output.trim().split("\n");
+    // Summary line is last and looks like: " 5 files changed, 100 insertions(+), 20 deletions(-)"
+    const summaryLine = lines[lines.length - 1];
+    if (!summaryLine) {
+        return { filesChanged: 0, linesAdded: 0 };
+    }
+    const filesMatch = summaryLine.match(/(\d+)\s+files?\s+changed/);
+    const insertionsMatch = summaryLine.match(/(\d+)\s+insertions?\(\+\)/);
+    return {
+        filesChanged: filesMatch ? parseInt(filesMatch[1], 10) : 0,
+        linesAdded: insertionsMatch ? parseInt(insertionsMatch[1], 10) : 0,
+    };
+}
 /**
  * Create or reuse a worktree for an issue
  * @param baseBranch - Optional branch to use as base instead of origin/main (for chain mode)
@@ -590,6 +616,9 @@ async function executePhase(issueNumber, phase, config, sessionId, worktreePath,
         // Execute using Claude Agent SDK
         // Note: Don't resume sessions when switching to worktree (different cwd breaks resume)
         const canResume = sessionId && !shouldUseWorktree;
+        // Get MCP servers config if enabled
+        // Reads from Claude Desktop config and passes to SDK for headless MCP support
+        const mcpServers = config.mcp ? getMcpServersConfig() : undefined;
         const queryInstance = query({
             prompt,
             options: {
@@ -607,6 +636,8 @@ async function executePhase(issueNumber, phase, config, sessionId, worktreePath,
                 ...(canResume ? { resume: sessionId } : {}),
                 // Configure smart tests and worktree isolation via environment
                 env,
+                // Pass MCP servers for headless mode (AC-2)
+                ...(mcpServers ? { mcpServers } : {}),
             },
         });
         // Stream and process messages
@@ -976,6 +1007,13 @@ export async function runCommand(issues, options) {
             console.log("");
         }
     }
+    // Validate QA gate requirements
+    if (mergedOptions.qaGate && !mergedOptions.chain) {
+        console.log(chalk.red("❌ --qa-gate requires --chain flag"));
+        console.log(chalk.gray("   QA gate ensures each issue passes QA before the next issue starts."));
+        console.log(chalk.gray("   Usage: npx sequant run 1 2 3 --sequential --chain --qa-gate"));
+        return;
+    }
     // Sort issues by dependencies (if more than one issue)
     if (issueNumbers.length > 1 && !batches) {
         const originalOrder = [...issueNumbers];
@@ -990,6 +1028,10 @@ export async function runCommand(issues, options) {
     const explicitPhases = mergedOptions.phases
         ? mergedOptions.phases.split(",").map((p) => p.trim())
         : null;
+    // Determine MCP enablement: CLI flag (--no-mcp) → settings.run.mcp → default (true)
+    const mcpEnabled = mergedOptions.noMcp
+        ? false
+        : (settings.run.mcp ?? DEFAULT_CONFIG.mcp);
     const config = {
         ...DEFAULT_CONFIG,
         phases: explicitPhases ?? DEFAULT_PHASES,
@@ -1000,6 +1042,7 @@ export async function runCommand(issues, options) {
         qualityLoop: mergedOptions.qualityLoop ?? false,
         maxIterations: mergedOptions.maxIterations ?? DEFAULT_CONFIG.maxIterations,
         noSmartTests: mergedOptions.noSmartTests ?? false,
+        mcp: mcpEnabled,
     };
     // Initialize log writer if JSON logging enabled
     // Default: enabled via settings (logJson: true), can be disabled with --no-log
@@ -1074,6 +1117,9 @@ export async function runCommand(issues, options) {
     if (mergedOptions.chain) {
         console.log(chalk.gray(`  Chain mode: enabled (each issue branches from previous)`));
     }
+    if (mergedOptions.qaGate) {
+        console.log(chalk.gray(`  QA gate: enabled (chain waits for QA pass)`));
+    }
     // Fetch issue info for all issues first
     const issueInfoMap = new Map();
     for (const issueNumber of issueNumbers) {
@@ -1150,6 +1196,27 @@ export async function runCommand(issues, options) {
                     break;
                 }
                 if (!result.success) {
+                    // Check if QA gate is enabled and QA specifically failed
+                    if (mergedOptions.qaGate) {
+                        const qaResult = result.phaseResults.find((p) => p.phase === "qa");
+                        const qaFailed = qaResult && !qaResult.success;
+                        if (qaFailed) {
+                            // QA gate: pause chain with clear messaging
+                            console.log(chalk.yellow("\n  ⏸️  QA Gate"));
+                            console.log(chalk.yellow(`     Issue #${issueNumber} QA did not pass. Chain paused.`));
+                            console.log(chalk.gray("     Fix QA issues and re-run, or run /loop to auto-fix."));
+                            // Update state to waiting_for_qa_gate
+                            if (stateManager) {
+                                try {
+                                    await stateManager.updateIssueStatus(issueNumber, "waiting_for_qa_gate");
+                                }
+                                catch {
+                                    // State tracking errors shouldn't stop execution
+                                }
+                            }
+                            break;
+                        }
+                    }
                     const chainInfo = mergedOptions.chain ? " (chain stopped)" : "";
                     console.log(chalk.yellow(`\n  ⚠️  Issue #${issueNumber} failed, stopping sequential execution${chainInfo}`));
                     break;
@@ -1186,12 +1253,93 @@ export async function runCommand(issues, options) {
         if (logWriter) {
             logPath = await logWriter.finalize();
         }
+        // Calculate success/failure counts
+        const passed = results.filter((r) => r.success).length;
+        const failed = results.filter((r) => !r.success).length;
+        // Record metrics (local analytics)
+        if (!config.dryRun && results.length > 0) {
+            try {
+                const metricsWriter = new MetricsWriter({ verbose: config.verbose });
+                // Calculate total duration
+                const totalDuration = results.reduce((sum, r) => sum + (r.durationSeconds ?? 0), 0);
+                // Get unique phases from all results
+                const allPhases = new Set();
+                for (const result of results) {
+                    for (const phaseResult of result.phaseResults) {
+                        // Only include phases that are valid MetricPhases
+                        const phase = phaseResult.phase;
+                        if ([
+                            "spec",
+                            "security-review",
+                            "testgen",
+                            "exec",
+                            "test",
+                            "qa",
+                            "loop",
+                        ].includes(phase)) {
+                            allPhases.add(phase);
+                        }
+                    }
+                }
+                // Calculate aggregate metrics from worktrees
+                let totalFilesChanged = 0;
+                let totalLinesAdded = 0;
+                let totalQaIterations = 0;
+                for (const result of results) {
+                    const worktreeInfo = worktreeMap.get(result.issueNumber);
+                    if (worktreeInfo?.path) {
+                        const stats = getWorktreeDiffStats(worktreeInfo.path);
+                        totalFilesChanged += stats.filesChanged;
+                        totalLinesAdded += stats.linesAdded;
+                    }
+                    // Count QA iterations (loop phases indicate retries)
+                    if (result.loopTriggered) {
+                        totalQaIterations += result.phaseResults.filter((p) => p.phase === "loop").length;
+                    }
+                }
+                // Build CLI flags for metrics
+                const cliFlags = [];
+                if (mergedOptions.sequential)
+                    cliFlags.push("--sequential");
+                if (mergedOptions.chain)
+                    cliFlags.push("--chain");
+                if (mergedOptions.qaGate)
+                    cliFlags.push("--qa-gate");
+                if (mergedOptions.qualityLoop)
+                    cliFlags.push("--quality-loop");
+                if (mergedOptions.testgen)
+                    cliFlags.push("--testgen");
+                // Record the run
+                await metricsWriter.recordRun({
+                    issues: issueNumbers,
+                    phases: Array.from(allPhases),
+                    outcome: determineOutcome(passed, results.length),
+                    duration: totalDuration,
+                    model: process.env.ANTHROPIC_MODEL ?? "opus",
+                    flags: cliFlags,
+                    metrics: {
+                        tokensUsed: 0, // Token tracking not available from SDK
+                        filesChanged: totalFilesChanged,
+                        linesAdded: totalLinesAdded,
+                        acceptanceCriteria: 0, // Would need to parse from issue
+                        qaIterations: totalQaIterations,
+                    },
+                });
+                if (config.verbose) {
+                    console.log(chalk.gray(`  📊 Metrics recorded to .sequant/metrics.json`));
+                }
+            }
+            catch (metricsError) {
+                // Metrics recording errors shouldn't stop execution
+                if (config.verbose) {
+                    console.log(chalk.yellow(`  ⚠️  Metrics recording error: ${metricsError}`));
+                }
+            }
+        }
         // Summary
         console.log(chalk.blue("\n" + "━".repeat(50)));
         console.log(chalk.blue("  Summary"));
         console.log(chalk.blue("━".repeat(50)));
-        const passed = results.filter((r) => r.success).length;
-        const failed = results.filter((r) => !r.success).length;
         console.log(chalk.gray(`\n  Results: ${chalk.green(`${passed} passed`)}, ${chalk.red(`${failed} failed`)}`));
         for (const result of results) {
             const status = result.success ? chalk.green("✓") : chalk.red("✗");

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

@@ -0,0 +1,60 @@
+/**
+ * sequant state - Manage workflow state for existing worktrees
+ *
+ * Provides commands to bootstrap, rebuild, and clean up workflow state:
+ * - init: Populate state for untracked worktrees
+ * - rebuild: Recreate entire state from git worktrees + logs
+ * - clean: Remove entries for worktrees that no longer exist
+ */
+export interface StateInitOptions {
+    /** Output as JSON */
+    json?: boolean;
+    /** Enable verbose output */
+    verbose?: boolean;
+}
+export interface StateRebuildOptions {
+    /** Output as JSON */
+    json?: boolean;
+    /** Enable verbose output */
+    verbose?: boolean;
+    /** Force rebuild without confirmation (skip backup warning) */
+    force?: boolean;
+}
+export interface StateCleanOptions {
+    /** Output as JSON */
+    json?: boolean;
+    /** Enable verbose output */
+    verbose?: boolean;
+    /** Only show what would be cleaned (don't modify) */
+    dryRun?: boolean;
+    /** Remove entries older than this many days */
+    maxAge?: number;
+    /** Remove all orphaned entries (both merged and abandoned) in one step */
+    all?: boolean;
+}
+/**
+ * Initialize state for untracked worktrees
+ *
+ * Scans for worktrees with issue-* or feature/* patterns,
+ * extracts issue numbers, fetches titles from GitHub,
+ * and populates state file with reasonable defaults.
+ */
+export declare function stateInitCommand(options?: StateInitOptions): Promise<void>;
+/**
+ * Rebuild entire state from scratch
+ *
+ * Combines worktree discovery with log-based state reconstruction.
+ * Creates backup of existing state before rebuilding.
+ */
+export declare function stateRebuildCommand(options?: StateRebuildOptions): Promise<void>;
+/**
+ * Clean up orphaned state entries
+ *
+ * Removes entries for worktrees that no longer exist.
+ * Detects merged PRs and auto-removes them.
+ */
+export declare function stateCleanCommand(options?: StateCleanOptions): Promise<void>;
+/**
+ * Main state command handler (routes to subcommands)
+ */
+export declare function stateCommand(subcommand: string | undefined, options?: StateInitOptions & StateRebuildOptions & StateCleanOptions): Promise<void>;