sequant 1.16.0 → 1.17.0

package/dist/src/lib/workflow/run-reflect.js

@@ -0,0 +1,191 @@
+/**
+ * Run reflection analysis — analyzes completed run data and suggests improvements.
+ *
+ * Used by the `--reflect` flag on `sequant run` to provide post-run insights.
+ */
+const MAX_OUTPUT_LINES = 10;
+/**
+ * Analyze a completed run and return observations + suggestions.
+ */
+export function analyzeRun(input) {
+    const observations = [];
+    const suggestions = [];
+    analyzeTimingPatterns(input, observations, suggestions);
+    detectPhaseMismatches(input, observations, suggestions);
+    suggestImprovements(input, observations, suggestions);
+    return { observations, suggestions };
+}
+/**
+ * Compare phase durations across issues to find timing anomalies.
+ */
+function analyzeTimingPatterns(input, observations, suggestions) {
+    const { results } = input;
+    // Compare spec phase durations (needs 2+ issues)
+    const specTimings = results
+        .map((r) => ({
+        issue: r.issueNumber,
+        duration: r.phaseResults.find((p) => p.phase === "spec")?.durationSeconds,
+    }))
+        .filter((t) => t.duration != null);
+    if (specTimings.length >= 2) {
+        const min = Math.min(...specTimings.map((t) => t.duration));
+        const max = Math.max(...specTimings.map((t) => t.duration));
+        // If spec times are similar (within 30%) despite different issues, flag it
+        if (max > 0 && min / max > 0.7 && max - min < 120) {
+            observations.push(`Spec times similar across issues (${formatSec(min)}–${formatSec(max)}) despite varying complexity`);
+            suggestions.push("Consider `--phases exec,qa` for simple fixes to skip spec");
+        }
+    }
+    // Flag individual phases that took unusually long
+    for (const result of results) {
+        for (const phase of result.phaseResults) {
+            if (phase.phase === "qa" &&
+                phase.durationSeconds &&
+                phase.durationSeconds > 300) {
+                observations.push(`#${result.issueNumber} QA took ${formatSec(phase.durationSeconds)}`);
+                suggestions.push("Long QA may indicate sub-agent spawning issues");
+                break;
+            }
+        }
+    }
+}
+/**
+ * Detect mismatches between file changes and executed phases.
+ */
+function detectPhaseMismatches(input, observations, suggestions) {
+    const { runLog, results } = input;
+    // Check fileDiffStats from runLog for .tsx/.jsx changes without test phase
+    if (runLog?.issues) {
+        for (const issueLog of runLog.issues) {
+            const phases = issueLog.phases.map((p) => p.phase);
+            const hasTestPhase = phases.includes("test");
+            if (hasTestPhase)
+                continue;
+            // Collect all modified files across phases
+            const modifiedFiles = [];
+            for (const phase of issueLog.phases) {
+                if (phase.fileDiffStats) {
+                    modifiedFiles.push(...phase.fileDiffStats.map((f) => f.path));
+                }
+                if (phase.filesModified) {
+                    modifiedFiles.push(...phase.filesModified);
+                }
+            }
+            const hasTsxFiles = modifiedFiles.some((f) => f.endsWith(".tsx") || f.endsWith(".jsx"));
+            if (hasTsxFiles) {
+                observations.push(`#${issueLog.issueNumber} modified .tsx files but no browser test ran`);
+                suggestions.push(`Add \`ui\` label to #${issueLog.issueNumber} for browser testing`);
+            }
+        }
+    }
+    // Fallback: check labels if no runLog
+    if (!runLog) {
+        for (const result of results) {
+            const info = input.issueInfoMap.get(result.issueNumber);
+            const labels = info?.labels ?? [];
+            const hasUiLabel = labels.some((l) => ["ui", "frontend", "admin"].includes(l.toLowerCase()));
+            const hasTestPhase = result.phaseResults.some((p) => p.phase === "test");
+            if (hasUiLabel && !hasTestPhase) {
+                observations.push(`#${result.issueNumber} has UI label but no test phase ran`);
+                suggestions.push("Include test phase for UI-labeled issues");
+            }
+        }
+    }
+}
+/**
+ * Suggest workflow improvements based on run patterns.
+ */
+function suggestImprovements(input, observations, suggestions) {
+    const { results, config } = input;
+    // Check if all issues ran the same phases
+    if (results.length >= 2) {
+        const phaseSets = results.map((r) => r.phaseResults.map((p) => p.phase).join(","));
+        const allSame = phaseSets.every((s) => s === phaseSets[0]);
+        if (allSame) {
+            observations.push("All issues ran identical phases despite different requirements");
+            suggestions.push("Use `/solve` first to get per-issue phase recommendations");
+        }
+    }
+    // Check if quality loop was triggered
+    const loopIssues = results.filter((r) => r.loopTriggered);
+    if (loopIssues.length > 0) {
+        const issueNums = loopIssues.map((r) => `#${r.issueNumber}`).join(", ");
+        observations.push(`Quality loop triggered for ${issueNums}`);
+        suggestions.push("Consider adding `complex` label upfront for similar issues");
+    }
+    // Check for failed issues
+    const failedIssues = results.filter((r) => !r.success);
+    if (failedIssues.length > 0 && results.length > 1) {
+        const failRate = ((failedIssues.length / results.length) * 100).toFixed(0);
+        observations.push(`${failRate}% failure rate (${failedIssues.length}/${results.length})`);
+    }
+    // Suggest quality loop if not enabled and failures occurred
+    if (!config.qualityLoop && failedIssues.length > 0) {
+        suggestions.push("Enable `--quality-loop` to auto-retry failed phases");
+    }
+}
+/**
+ * Format reflection output as a box with observations and suggestions.
+ * Enforces max 10 content lines.
+ */
+export function formatReflection(output) {
+    const { observations, suggestions } = output;
+    if (observations.length === 0 && suggestions.length === 0) {
+        return "";
+    }
+    const lines = [];
+    // Collect all content lines
+    const contentLines = [];
+    for (const obs of observations) {
+        contentLines.push(`  \u2022 ${obs}`);
+    }
+    for (const sug of suggestions) {
+        contentLines.push(`  \u2022 ${sug}`);
+    }
+    // Truncate if needed
+    const truncated = contentLines.length > MAX_OUTPUT_LINES;
+    const displayLines = truncated
+        ? contentLines.slice(0, MAX_OUTPUT_LINES - 1)
+        : contentLines;
+    // Calculate box width
+    const maxLineLen = Math.max(...displayLines.map((l) => l.length), truncated ? 30 : 0, 20);
+    const boxWidth = Math.min(Math.max(maxLineLen + 4, 40), 66);
+    // Build box
+    lines.push(`  \u250C\u2500 Run Analysis ${"─".repeat(Math.max(boxWidth - 16, 0))}\u2510`);
+    lines.push(`  \u2502${" ".repeat(boxWidth - 2)}\u2502`);
+    if (observations.length > 0) {
+        lines.push(`  \u2502  Observations:${" ".repeat(Math.max(boxWidth - 17, 0))}\u2502`);
+        for (const line of displayLines.slice(0, observations.length)) {
+            lines.push(`  \u2502${padRight(line, boxWidth - 2)}\u2502`);
+        }
+        lines.push(`  \u2502${" ".repeat(boxWidth - 2)}\u2502`);
+    }
+    const sugLines = displayLines.slice(observations.length);
+    if (sugLines.length > 0) {
+        lines.push(`  \u2502  Suggestions:${" ".repeat(Math.max(boxWidth - 16, 0))}\u2502`);
+        for (const line of sugLines) {
+            lines.push(`  \u2502${padRight(line, boxWidth - 2)}\u2502`);
+        }
+        lines.push(`  \u2502${" ".repeat(boxWidth - 2)}\u2502`);
+    }
+    if (truncated) {
+        const remaining = contentLines.length - (MAX_OUTPUT_LINES - 1);
+        const moreText = `  ... and ${remaining} more`;
+        lines.push(`  \u2502${padRight(moreText, boxWidth - 2)}\u2502`);
+        lines.push(`  \u2502${" ".repeat(boxWidth - 2)}\u2502`);
+    }
+    lines.push(`  \u2514${"─".repeat(boxWidth - 2)}\u2518`);
+    return lines.join("\n");
+}
+function padRight(str, len) {
+    return str.length >= len
+        ? str.slice(0, len)
+        : str + " ".repeat(len - str.length);
+}
+function formatSec(seconds) {
+    if (seconds < 60)
+        return `${seconds.toFixed(0)}s`;
+    const mins = Math.floor(seconds / 60);
+    const secs = Math.round(seconds % 60);
+    return `${mins}m ${secs}s`;
+}

package/dist/src/lib/workflow/state-cleanup.d.ts

@@ -0,0 +1,79 @@
+/**
+ * State cleanup and reconciliation utilities
+ *
+ * @module state-cleanup
+ * @example
+ * ```typescript
+ * import { cleanupStaleEntries, reconcileStateAtStartup } from './state-cleanup';
+ *
+ * // Clean up orphaned entries
+ * const result = await cleanupStaleEntries({ dryRun: true });
+ * console.log(`Would remove ${result.removed.length} entries`);
+ *
+ * // Reconcile state at startup
+ * const reconcileResult = await reconcileStateAtStartup();
+ * console.log(`Advanced ${reconcileResult.advanced.length} issues to merged`);
+ * ```
+ */
+export interface CleanupOptions {
+    /** State file path (default: .sequant/state.json) */
+    statePath?: string;
+    /** Only report what would be cleaned (don't modify) */
+    dryRun?: boolean;
+    /** Enable verbose logging */
+    verbose?: boolean;
+    /** Remove issues older than this many days */
+    maxAgeDays?: number;
+    /** Remove all orphaned entries (both merged and abandoned) in one step */
+    removeAll?: boolean;
+}
+export interface CleanupResult {
+    /** Whether cleanup was successful */
+    success: boolean;
+    /** Issues that were removed or would be removed */
+    removed: number[];
+    /** Issues that were marked as orphaned (abandoned) */
+    orphaned: number[];
+    /** Issues detected as merged PRs */
+    merged: number[];
+    /** Error message if failed */
+    error?: string;
+}
+/**
+ * Clean up stale and orphaned entries from workflow state
+ *
+ * - Checks GitHub to detect if associated PR was merged
+ * - Orphaned entries with merged PRs get status "merged" and are removed automatically
+ * - Orphaned entries without merged PRs get status "abandoned" (kept for review)
+ * - Use removeAll to remove both merged and abandoned orphaned entries in one step
+ * - Use maxAgeDays to remove old merged/abandoned issues
+ */
+export declare function cleanupStaleEntries(options?: CleanupOptions): Promise<CleanupResult>;
+export interface ReconcileOptions {
+    /** State file path (default: .sequant/state.json) */
+    statePath?: string;
+    /** Enable verbose logging */
+    verbose?: boolean;
+}
+export interface ReconcileResult {
+    /** Whether reconciliation was successful */
+    success: boolean;
+    /** Issues that were advanced from ready_for_merge to merged */
+    advanced: number[];
+    /** Issues checked but still ready_for_merge */
+    stillPending: number[];
+    /** Error message if failed */
+    error?: string;
+}
+/**
+ * Lightweight state reconciliation at run start
+ *
+ * Checks issues in `ready_for_merge` state and advances them to `merged`
+ * if their PRs are merged or their branches are in main.
+ *
+ * This prevents re-running already completed issues.
+ *
+ * @param options - Reconciliation options
+ * @returns Result with lists of advanced and still-pending issues
+ */
+export declare function reconcileStateAtStartup(options?: ReconcileOptions): Promise<ReconcileResult>;

package/dist/src/lib/workflow/state-cleanup.js

@@ -0,0 +1,250 @@
+/**
+ * State cleanup and reconciliation utilities
+ *
+ * @module state-cleanup
+ * @example
+ * ```typescript
+ * import { cleanupStaleEntries, reconcileStateAtStartup } from './state-cleanup';
+ *
+ * // Clean up orphaned entries
+ * const result = await cleanupStaleEntries({ dryRun: true });
+ * console.log(`Would remove ${result.removed.length} entries`);
+ *
+ * // Reconcile state at startup
+ * const reconcileResult = await reconcileStateAtStartup();
+ * console.log(`Advanced ${reconcileResult.advanced.length} issues to merged`);
+ * ```
+ */
+import { spawnSync } from "child_process";
+import { StateManager } from "./state-manager.js";
+import { checkPRMergeStatus, isIssueMergedIntoMain } from "./pr-status.js";
+/**
+ * Get list of active worktree paths
+ */
+function getActiveWorktrees() {
+    const result = spawnSync("git", ["worktree", "list", "--porcelain"], {
+        stdio: "pipe",
+    });
+    if (result.status !== 0) {
+        return [];
+    }
+    const output = result.stdout.toString();
+    const paths = [];
+    for (const line of output.split("\n")) {
+        if (line.startsWith("worktree ")) {
+            paths.push(line.substring(9));
+        }
+    }
+    return paths;
+}
+/**
+ * Clean up stale and orphaned entries from workflow state
+ *
+ * - Checks GitHub to detect if associated PR was merged
+ * - Orphaned entries with merged PRs get status "merged" and are removed automatically
+ * - Orphaned entries without merged PRs get status "abandoned" (kept for review)
+ * - Use removeAll to remove both merged and abandoned orphaned entries in one step
+ * - Use maxAgeDays to remove old merged/abandoned issues
+ */
+export async function cleanupStaleEntries(options = {}) {
+    const manager = new StateManager({
+        statePath: options.statePath,
+        verbose: options.verbose,
+    });
+    if (!manager.stateExists()) {
+        return {
+            success: true,
+            removed: [],
+            orphaned: [],
+            merged: [],
+        };
+    }
+    try {
+        const state = await manager.getState();
+        const removed = [];
+        const orphaned = [];
+        const merged = [];
+        // Get list of active worktrees
+        const activeWorktrees = getActiveWorktrees();
+        for (const [issueNumStr, issueState] of Object.entries(state.issues)) {
+            const issueNum = parseInt(issueNumStr, 10);
+            // Check if worktree exists (if issue has one)
+            if (issueState.worktree &&
+                !activeWorktrees.includes(issueState.worktree)) {
+                if (options.verbose) {
+                    console.log(`🔍 Orphaned: #${issueNum} (worktree not found: ${issueState.worktree})`);
+                }
+                // Check if this issue has a PR and if it's merged
+                let prMerged = false;
+                if (issueState.pr?.number) {
+                    if (options.verbose) {
+                        console.log(`   Checking PR #${issueState.pr.number} status...`);
+                    }
+                    const prStatus = checkPRMergeStatus(issueState.pr.number);
+                    prMerged = prStatus === "MERGED";
+                    if (options.verbose) {
+                        console.log(`   PR status: ${prStatus ?? "unknown"}`);
+                    }
+                }
+                if (!options.dryRun) {
+                    if (prMerged || issueState.status === "merged") {
+                        // Merged PRs are auto-removed
+                        merged.push(issueNum);
+                        removed.push(issueNum);
+                        if (options.verbose) {
+                            console.log(`   ✓ Merged PR detected, removing entry`);
+                        }
+                        delete state.issues[issueNumStr];
+                    }
+                    else if (issueState.status === "abandoned" || options.removeAll) {
+                        // Already abandoned or removeAll flag - remove it
+                        orphaned.push(issueNum);
+                        removed.push(issueNum);
+                        if (options.verbose) {
+                            console.log(`   ✓ Removing abandoned entry`);
+                        }
+                        delete state.issues[issueNumStr];
+                    }
+                    else {
+                        // Mark as abandoned (kept for review)
+                        orphaned.push(issueNum);
+                        issueState.status = "abandoned";
+                        if (options.verbose) {
+                            console.log(`   → Marked as abandoned (kept for review)`);
+                        }
+                    }
+                }
+                else {
+                    // Dry run - report what would happen
+                    if (prMerged || issueState.status === "merged") {
+                        merged.push(issueNum);
+                        removed.push(issueNum);
+                    }
+                    else if (issueState.status === "abandoned" || options.removeAll) {
+                        orphaned.push(issueNum);
+                        removed.push(issueNum);
+                    }
+                    else {
+                        orphaned.push(issueNum);
+                    }
+                }
+                continue;
+            }
+            // Check age for merged/abandoned issues
+            if (options.maxAgeDays &&
+                (issueState.status === "merged" || issueState.status === "abandoned")) {
+                const lastActivity = new Date(issueState.lastActivity);
+                const ageDays = (Date.now() - lastActivity.getTime()) / (1000 * 60 * 60 * 24);
+                if (ageDays > options.maxAgeDays) {
+                    removed.push(issueNum);
+                    if (options.verbose) {
+                        console.log(`🗑️  Stale: #${issueNum} (${Math.floor(ageDays)} days old)`);
+                    }
+                    if (!options.dryRun) {
+                        delete state.issues[issueNumStr];
+                    }
+                }
+            }
+        }
+        // Save updated state
+        if (!options.dryRun && (removed.length > 0 || orphaned.length > 0)) {
+            await manager.saveState(state);
+        }
+        return {
+            success: true,
+            removed,
+            orphaned,
+            merged,
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            removed: [],
+            orphaned: [],
+            merged: [],
+            error: String(error),
+        };
+    }
+}
+/**
+ * Lightweight state reconciliation at run start
+ *
+ * Checks issues in `ready_for_merge` state and advances them to `merged`
+ * if their PRs are merged or their branches are in main.
+ *
+ * This prevents re-running already completed issues.
+ *
+ * @param options - Reconciliation options
+ * @returns Result with lists of advanced and still-pending issues
+ */
+export async function reconcileStateAtStartup(options = {}) {
+    const manager = new StateManager({
+        statePath: options.statePath,
+        verbose: options.verbose,
+    });
+    // Graceful degradation: if state file doesn't exist, skip
+    if (!manager.stateExists()) {
+        return {
+            success: true,
+            advanced: [],
+            stillPending: [],
+        };
+    }
+    try {
+        const state = await manager.getState();
+        const advanced = [];
+        const stillPending = [];
+        // Find issues in ready_for_merge state
+        for (const [issueNumStr, issueState] of Object.entries(state.issues)) {
+            if (issueState.status !== "ready_for_merge") {
+                continue;
+            }
+            const issueNum = parseInt(issueNumStr, 10);
+            let isMerged = false;
+            // Check 1: If we have PR info, check PR status via gh
+            if (issueState.pr?.number) {
+                const prStatus = checkPRMergeStatus(issueState.pr.number);
+                if (prStatus === "MERGED") {
+                    isMerged = true;
+                    if (options.verbose) {
+                        console.log(`  #${issueNum}: PR #${issueState.pr.number} is merged`);
+                    }
+                }
+            }
+            // Check 2: If no PR or PR check failed, check git for merged branch
+            if (!isMerged) {
+                isMerged = isIssueMergedIntoMain(issueNum);
+                if (isMerged && options.verbose) {
+                    console.log(`  #${issueNum}: Branch merged into main (git check)`);
+                }
+            }
+            if (isMerged) {
+                // Advance state to merged
+                issueState.status = "merged";
+                issueState.lastActivity = new Date().toISOString();
+                advanced.push(issueNum);
+            }
+            else {
+                stillPending.push(issueNum);
+            }
+        }
+        // Save state if any issues were advanced
+        if (advanced.length > 0) {
+            await manager.saveState(state);
+        }
+        return {
+            success: true,
+            advanced,
+            stillPending,
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            advanced: [],
+            stillPending: [],
+            error: String(error),
+        };
+    }
+}

package/dist/src/lib/workflow/state-rebuild.d.ts

@@ -0,0 +1,38 @@
+/**
+ * State reconstruction from run logs
+ *
+ * @module state-rebuild
+ * @example
+ * ```typescript
+ * import { rebuildStateFromLogs } from './state-rebuild';
+ *
+ * // Rebuild state from run logs
+ * const result = await rebuildStateFromLogs();
+ * console.log(`Processed ${result.logsProcessed} logs, found ${result.issuesFound} issues`);
+ * ```
+ */
+export interface RebuildOptions {
+    /** Log directory path (default: .sequant/logs) */
+    logPath?: string;
+    /** State file path (default: .sequant/state.json) */
+    statePath?: string;
+    /** Enable verbose logging */
+    verbose?: boolean;
+}
+export interface RebuildResult {
+    /** Whether rebuild was successful */
+    success: boolean;
+    /** Number of log files processed */
+    logsProcessed: number;
+    /** Number of issues found */
+    issuesFound: number;
+    /** Error message if failed */
+    error?: string;
+}
+/**
+ * Rebuild workflow state from run logs
+ *
+ * Scans all run logs in .sequant/logs/ and reconstructs state
+ * based on the most recent activity for each issue.
+ */
+export declare function rebuildStateFromLogs(options?: RebuildOptions): Promise<RebuildResult>;