sequant 1.20.2 → 2.0.0

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

@@ -17,10 +17,11 @@
  * ```
  */
 import { z } from "zod";
+import { PhaseSchema } from "./types.js";
 /**
  * Workflow phases in order of execution
  */
-export declare const WORKFLOW_PHASES: readonly ["spec", "security-review", "exec", "testgen", "test", "verify", "qa", "loop", "merger"];
+export declare const WORKFLOW_PHASES: ("qa" | "loop" | "verify" | "spec" | "security-review" | "exec" | "testgen" | "test" | "merger")[];
 /**
  * Phase status - tracks individual phase progress
  */
@@ -28,38 +29,25 @@ export declare const PhaseStatusSchema: z.ZodEnum<{
     pending: "pending";
     skipped: "skipped";
     completed: "completed";
-    in_progress: "in_progress";
     failed: "failed";
+    in_progress: "in_progress";
 }>;
 export type PhaseStatus = z.infer<typeof PhaseStatusSchema>;
 /**
  * Issue status - tracks overall issue progress
  */
 export declare const IssueStatusSchema: z.ZodEnum<{
+    merged: "merged";
     in_progress: "in_progress";
     not_started: "not_started";
     waiting_for_qa_gate: "waiting_for_qa_gate";
     ready_for_merge: "ready_for_merge";
-    merged: "merged";
     blocked: "blocked";
     abandoned: "abandoned";
 }>;
 export type IssueStatus = z.infer<typeof IssueStatusSchema>;
-/**
- * Phase type
- */
-export declare const PhaseSchema: z.ZodEnum<{
-    loop: "loop";
-    verify: "verify";
-    spec: "spec";
-    exec: "exec";
-    qa: "qa";
-    "security-review": "security-review";
-    testgen: "testgen";
-    test: "test";
-    merger: "merger";
-}>;
-export type Phase = z.infer<typeof PhaseSchema>;
+export { PhaseSchema };
+export type { Phase } from "./types.js";
 /**
  * Phase marker stored in GitHub issue comments for cross-session detection.
  *
@@ -67,12 +55,12 @@ export type Phase = z.infer<typeof PhaseSchema>;
  */
 export declare const PhaseMarkerSchema: z.ZodObject<{
     phase: z.ZodEnum<{
+        qa: "qa";
         loop: "loop";
         verify: "verify";
         spec: "spec";
-        exec: "exec";
-        qa: "qa";
         "security-review": "security-review";
+        exec: "exec";
         testgen: "testgen";
         test: "test";
         merger: "merger";
@@ -81,12 +69,13 @@ export declare const PhaseMarkerSchema: z.ZodObject<{
         pending: "pending";
         skipped: "skipped";
         completed: "completed";
-        in_progress: "in_progress";
         failed: "failed";
+        in_progress: "in_progress";
     }>;
     timestamp: z.ZodString;
     pr: z.ZodOptional<z.ZodNumber>;
     error: z.ZodOptional<z.ZodString>;
+    commitSHA: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type PhaseMarker = z.infer<typeof PhaseMarkerSchema>;
 /**
@@ -97,8 +86,8 @@ export declare const PhaseStateSchema: z.ZodObject<{
         pending: "pending";
         skipped: "skipped";
         completed: "completed";
-        in_progress: "in_progress";
         failed: "failed";
+        in_progress: "in_progress";
     }>;
     startedAt: z.ZodOptional<z.ZodString>;
     completedAt: z.ZodOptional<z.ZodString>;
@@ -204,23 +193,23 @@ export declare const IssueStateSchema: z.ZodObject<{
     number: z.ZodNumber;
     title: z.ZodString;
     status: z.ZodEnum<{
+        merged: "merged";
         in_progress: "in_progress";
         not_started: "not_started";
         waiting_for_qa_gate: "waiting_for_qa_gate";
         ready_for_merge: "ready_for_merge";
-        merged: "merged";
         blocked: "blocked";
         abandoned: "abandoned";
     }>;
     worktree: z.ZodOptional<z.ZodString>;
     branch: z.ZodOptional<z.ZodString>;
     currentPhase: z.ZodOptional<z.ZodEnum<{
+        qa: "qa";
         loop: "loop";
         verify: "verify";
         spec: "spec";
-        exec: "exec";
-        qa: "qa";
         "security-review": "security-review";
+        exec: "exec";
         testgen: "testgen";
         test: "test";
         merger: "merger";
@@ -230,8 +219,8 @@ export declare const IssueStateSchema: z.ZodObject<{
             pending: "pending";
             skipped: "skipped";
             completed: "completed";
-            in_progress: "in_progress";
             failed: "failed";
+            in_progress: "in_progress";
         }>;
         startedAt: z.ZodOptional<z.ZodString>;
         completedAt: z.ZodOptional<z.ZodString>;
@@ -313,6 +302,7 @@ export declare const IssueStateSchema: z.ZodObject<{
         recommendation: z.ZodString;
     }, z.core.$strip>>;
     sessionId: z.ZodOptional<z.ZodString>;
+    resolvedAt: z.ZodOptional<z.ZodString>;
     lastActivity: z.ZodString;
     createdAt: z.ZodString;
 }, z.core.$strip>;
@@ -325,27 +315,28 @@ export type IssueState = z.infer<typeof IssueStateSchema>;
 export declare const WorkflowStateSchema: z.ZodObject<{
     version: z.ZodLiteral<1>;
     lastUpdated: z.ZodString;
+    lastSynced: z.ZodOptional<z.ZodString>;
     issues: z.ZodRecord<z.ZodString, z.ZodObject<{
         number: z.ZodNumber;
         title: z.ZodString;
         status: z.ZodEnum<{
+            merged: "merged";
             in_progress: "in_progress";
             not_started: "not_started";
             waiting_for_qa_gate: "waiting_for_qa_gate";
             ready_for_merge: "ready_for_merge";
-            merged: "merged";
             blocked: "blocked";
             abandoned: "abandoned";
         }>;
         worktree: z.ZodOptional<z.ZodString>;
         branch: z.ZodOptional<z.ZodString>;
         currentPhase: z.ZodOptional<z.ZodEnum<{
+            qa: "qa";
             loop: "loop";
             verify: "verify";
             spec: "spec";
-            exec: "exec";
-            qa: "qa";
             "security-review": "security-review";
+            exec: "exec";
             testgen: "testgen";
             test: "test";
             merger: "merger";
@@ -355,8 +346,8 @@ export declare const WorkflowStateSchema: z.ZodObject<{
                 pending: "pending";
                 skipped: "skipped";
                 completed: "completed";
-                in_progress: "in_progress";
                 failed: "failed";
+                in_progress: "in_progress";
             }>;
             startedAt: z.ZodOptional<z.ZodString>;
             completedAt: z.ZodOptional<z.ZodString>;
@@ -438,6 +429,7 @@ export declare const WorkflowStateSchema: z.ZodObject<{
             recommendation: z.ZodString;
         }, z.core.$strip>>;
         sessionId: z.ZodOptional<z.ZodString>;
+        resolvedAt: z.ZodOptional<z.ZodString>;
         lastActivity: z.ZodString;
         createdAt: z.ZodString;
     }, z.core.$strip>>;
@@ -476,3 +468,15 @@ export declare function createAcceptanceCriteria(items: AcceptanceCriterion[]):
  * Update acceptance criteria summary based on item statuses
  */
 export declare function updateAcceptanceCriteriaSummary(ac: AcceptanceCriteria): AcceptanceCriteria;
+/**
+ * Check if an issue status is terminal (resolved)
+ */
+export declare function isTerminalStatus(status: IssueStatus): boolean;
+/**
+ * Check if a resolved issue has expired based on TTL.
+ *
+ * @param entry - The issue state to check
+ * @param ttlDays - TTL in days. 0 = never auto-prune, -1 = prune immediately
+ * @param now - Current time (for testing)
+ */
+export declare function isExpired(entry: IssueState, ttlDays: number, now?: number): boolean;

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

@@ -18,20 +18,11 @@
  */
 import { z } from "zod";
 import { ScopeAssessmentSchema } from "../scope/types.js";
+import { PhaseSchema } from "./types.js";
 /**
  * Workflow phases in order of execution
  */
-export const WORKFLOW_PHASES = [
-    "spec",
-    "security-review",
-    "exec",
-    "testgen",
-    "test",
-    "verify",
-    "qa",
-    "loop",
-    "merger",
-];
+export const WORKFLOW_PHASES = PhaseSchema.options;
 /**
  * Phase status - tracks individual phase progress
  */
@@ -54,20 +45,8 @@ export const IssueStatusSchema = z.enum([
     "blocked", // Waiting on external input or dependency
     "abandoned", // Work stopped, will not continue
 ]);
-/**
- * Phase type
- */
-export const PhaseSchema = z.enum([
-    "spec",
-    "security-review",
-    "exec",
-    "testgen",
-    "test",
-    "verify",
-    "qa",
-    "loop",
-    "merger",
-]);
+// Re-export canonical Phase types from types.ts (single source of truth)
+export { PhaseSchema };
 /**
  * Phase marker stored in GitHub issue comments for cross-session detection.
  *
@@ -84,6 +63,8 @@ export const PhaseMarkerSchema = z.object({
     pr: z.number().int().positive().optional(),
     /** Error message if phase failed */
     error: z.string().optional(),
+    /** Git HEAD SHA at time of phase completion (used for incremental QA) */
+    commitSHA: z.string().optional(),
 });
 /**
  * Individual phase state within an issue
@@ -200,6 +181,8 @@ export const IssueStateSchema = z.object({
     scopeAssessment: ScopeAssessmentSchema.optional(),
     /** Claude session ID (for resume) */
     sessionId: z.string().optional(),
+    /** When the issue transitioned to a terminal status (merged/abandoned/closed) */
+    resolvedAt: z.string().datetime().optional(),
     /** Most recent activity timestamp */
     lastActivity: z.string().datetime(),
     /** When this issue was first tracked */
@@ -215,6 +198,8 @@ export const WorkflowStateSchema = z.object({
     version: z.literal(1),
     /** When the state file was last updated */
     lastUpdated: z.string().datetime(),
+    /** When state was last reconciled with GitHub */
+    lastSynced: z.string().datetime().optional(),
     /** State for all tracked issues, keyed by issue number */
     issues: z.record(z.string(), IssueStateSchema),
 });
@@ -307,3 +292,28 @@ export function updateAcceptanceCriteriaSummary(ac) {
     };
     return { ...ac, summary };
 }
+/** Terminal statuses that indicate an issue is resolved */
+const TERMINAL_STATUSES = ["merged", "abandoned"];
+/**
+ * Check if an issue status is terminal (resolved)
+ */
+export function isTerminalStatus(status) {
+    return TERMINAL_STATUSES.includes(status);
+}
+/**
+ * Check if a resolved issue has expired based on TTL.
+ *
+ * @param entry - The issue state to check
+ * @param ttlDays - TTL in days. 0 = never auto-prune, -1 = prune immediately
+ * @param now - Current time (for testing)
+ */
+export function isExpired(entry, ttlDays, now = Date.now()) {
+    if (ttlDays === 0)
+        return false; // opt-out
+    if (!entry.resolvedAt)
+        return false; // not resolved
+    if (ttlDays < 0)
+        return true; // prune immediately
+    const age = now - new Date(entry.resolvedAt).getTime();
+    return age > ttlDays * 86_400_000;
+}

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

@@ -24,5 +24,7 @@ export type { RebuildOptions, RebuildResult } from "./state-rebuild.js";
 export { rebuildStateFromLogs } from "./state-rebuild.js";
 export type { DiscoverOptions, DiscoveredWorktree, SkippedWorktree, DiscoverResult, } from "./worktree-discovery.js";
 export { discoverUntrackedWorktrees } from "./worktree-discovery.js";
-export type { CleanupOptions, CleanupResult, ReconcileOptions, ReconcileResult, } from "./state-cleanup.js";
+export type { CleanupOptions, CleanupResult, ReconcileOptions as StartupReconcileOptions, ReconcileResult as StartupReconcileResult, } from "./state-cleanup.js";
 export { cleanupStaleEntries, reconcileStateAtStartup, } from "./state-cleanup.js";
+export type { ReconcileOptions, ReconcileResult, DriftAction, DriftType, } from "./reconcile.js";
+export { reconcileState, classifyDrift, getNextActionHint, formatRelativeTime, } from "./reconcile.js";

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

@@ -22,3 +22,4 @@ export { checkPRMergeStatus, isBranchMergedIntoMain, isIssueMergedIntoMain, } fr
 export { rebuildStateFromLogs } from "./state-rebuild.js";
 export { discoverUntrackedWorktrees } from "./worktree-discovery.js";
 export { cleanupStaleEntries, reconcileStateAtStartup, } from "./state-cleanup.js";
+export { reconcileState, classifyDrift, getNextActionHint, formatRelativeTime, } from "./reconcile.js";

package/dist/src/lib/workflow/types.d.ts

@@ -1,10 +1,33 @@
 /**
  * Core types for workflow execution
  */
+import { z } from "zod";
+import type { AiderSettings } from "../settings.js";
+import type { LogWriter } from "./log-writer.js";
+import type { StateManager } from "./state-manager.js";
+import type { ShutdownManager } from "../shutdown.js";
+import type { WorktreeInfo } from "./worktree-manager.js";
 /**
- * Available workflow phases
+ * Canonical Zod schema for all workflow phases.
+ *
+ * This is the single source of truth — state-schema.ts and run-log-schema.ts
+ * both reference this definition. Add new phases here only.
  */
-export type Phase = "spec" | "security-review" | "testgen" | "exec" | "test" | "qa" | "loop";
+export declare const PhaseSchema: z.ZodEnum<{
+    qa: "qa";
+    loop: "loop";
+    verify: "verify";
+    spec: "spec";
+    "security-review": "security-review";
+    exec: "exec";
+    testgen: "testgen";
+    test: "test";
+    merger: "merger";
+}>;
+/**
+ * Available workflow phases (inferred from PhaseSchema)
+ */
+export type Phase = z.infer<typeof PhaseSchema>;
 /**
  * Default phases for workflow execution
  */
@@ -25,8 +48,10 @@ export interface ExecutionConfig {
     skipVerification: boolean;
     /** Run issues sequentially */
     sequential: boolean;
-    /** Force parallel even with dependencies */
-    forceParallel: boolean;
+    /** Max concurrent issues in parallel mode (default: 3) */
+    concurrency: number;
+    /** Suppress per-issue spinners and console output (set true when running issues concurrently) */
+    parallel: boolean;
     /** Verbose output */
     verbose: boolean;
     /** Disable smart test detection */
@@ -41,13 +66,27 @@ export interface ExecutionConfig {
      * When false (--no-retry flag), no retry attempts are made.
      */
     retry?: boolean;
+    /**
+     * Agent driver to use for phase execution.
+     * Default: "claude-code"
+     */
+    agent?: string;
+    /**
+     * Aider-specific configuration. Passed to AiderDriver when agent is "aider".
+     */
+    aiderSettings?: AiderSettings;
+    /**
+     * Issue type detected from labels (e.g., "docs").
+     * Propagated as SEQUANT_ISSUE_TYPE env var to skills.
+     */
+    issueType?: string;
 }
 /**
  * Default execution configuration
  */
 export declare const DEFAULT_CONFIG: ExecutionConfig;
-import type { QaVerdict } from "./run-log-schema.js";
-export type { QaVerdict } from "./run-log-schema.js";
+import type { QaVerdict, QaSummary } from "./run-log-schema.js";
+export type { QaVerdict, QaSummary } from "./run-log-schema.js";
 /**
  * Result of executing a single phase
  */
@@ -60,6 +99,14 @@ export interface PhaseResult {
     output?: string;
     /** Parsed QA verdict (only for qa phase) */
     verdict?: QaVerdict;
+    /** Condensed QA summary with AC coverage (#434) */
+    summary?: QaSummary;
+    /** Last N lines of stderr captured from the agent process (#447) */
+    stderrTail?: string[];
+    /** Last N lines of stdout captured from the agent process (#447) */
+    stdoutTail?: string[];
+    /** Process exit code from the agent driver (#447) */
+    exitCode?: number;
 }
 /**
  * Result of executing all phases for an issue
@@ -76,6 +123,96 @@ export interface IssueResult {
     /** PR URL if created after successful QA */
     prUrl?: string;
 }
+/**
+ * CLI options for the run command, merged with settings and env config.
+ * Moved from batch-executor.ts for use in IssueExecutionContext (#402).
+ */
+export interface RunOptions {
+    phases?: string;
+    sequential?: boolean;
+    dryRun?: boolean;
+    verbose?: boolean;
+    timeout?: number;
+    logJson?: boolean;
+    noLog?: boolean;
+    logPath?: string;
+    qualityLoop?: boolean;
+    maxIterations?: number;
+    batch?: string[];
+    smartTests?: boolean;
+    noSmartTests?: boolean;
+    testgen?: boolean;
+    autoDetectPhases?: boolean;
+    /** Enable automatic worktree creation for issue isolation */
+    worktreeIsolation?: boolean;
+    /** Reuse existing worktrees instead of creating new ones */
+    reuseWorktrees?: boolean;
+    /** Suppress version warnings and non-essential output */
+    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;
+    /**
+     * Resume from last completed phase.
+     * Reads phase markers from GitHub issue comments and skips completed phases.
+     */
+    resume?: boolean;
+    /**
+     * Disable automatic retry with MCP fallback.
+     * When true, no retry attempts are made on phase failure.
+     * Useful for debugging to see the actual failure without retry masking it.
+     */
+    noRetry?: boolean;
+    /**
+     * Skip pre-PR rebase onto the base branch.
+     * When true, branches are not rebased before creating the PR.
+     * Use when you want to preserve branch state or handle rebasing manually.
+     */
+    noRebase?: boolean;
+    /**
+     * Skip PR creation after successful QA.
+     * When true, branches are pushed but no PR is created.
+     * Useful for manual workflows where PRs are created separately.
+     */
+    noPr?: boolean;
+    /**
+     * Force re-execution of issues even if they have completed status.
+     * Bypasses the pre-flight state guard that skips ready_for_merge/merged issues.
+     */
+    force?: boolean;
+    /**
+     * Analyze run results and suggest workflow improvements.
+     * Displays observations about timing patterns, phase mismatches, and
+     * actionable suggestions after the summary output.
+     */
+    reflect?: boolean;
+    /**
+     * Max concurrent issues in parallel mode (default: 3).
+     * Only applies when --sequential is not set.
+     */
+    concurrency?: number;
+    /**
+     * Agent driver for phase execution.
+     * Default: "claude-code"
+     */
+    agent?: string;
+}
 /**
  * CLI arguments for run command
  */
@@ -104,3 +241,68 @@ export interface BatchResult {
     issueResults: IssueResult[];
     success: boolean;
 }
+/**
+ * Callback type for per-phase progress updates.
+ * Used by parallel mode in run.ts to render phase status to the terminal.
+ */
+export type ProgressCallback = (issue: number, phase: string, event: "start" | "complete" | "failed", extra?: {
+    durationSeconds?: number;
+    error?: string;
+}) => void;
+/**
+ * Shared context for executing a batch of issues.
+ * Replaces 11 positional parameters in executeBatch (#402).
+ */
+export interface BatchExecutionContext {
+    config: ExecutionConfig;
+    options: RunOptions;
+    issueInfoMap: Map<number, {
+        title: string;
+        labels: string[];
+    }>;
+    worktreeMap: Map<number, WorktreeInfo>;
+    logWriter: LogWriter | null;
+    stateManager: StateManager | null;
+    shutdownManager?: ShutdownManager;
+    packageManager?: string;
+    baseBranch?: string;
+    onProgress?: ProgressCallback;
+}
+/**
+ * Context object for executing a single issue through the workflow.
+ * Replaces 15 positional parameters in runIssueWithLogging (#402).
+ */
+export interface IssueExecutionContext {
+    /** GitHub issue number */
+    issueNumber: number;
+    /** Issue title for display and PR creation */
+    title: string;
+    /** GitHub labels for phase detection and issue type */
+    labels: string[];
+    /** Execution configuration (phases, timeouts, flags) */
+    config: ExecutionConfig;
+    /** CLI options merged with settings and env */
+    options: RunOptions;
+    /** Services used during execution */
+    services: {
+        logWriter: LogWriter | null;
+        stateManager: StateManager | null;
+        shutdownManager?: ShutdownManager;
+    };
+    /** Worktree info (when worktree isolation is enabled) */
+    worktree?: {
+        path: string;
+        branch: string;
+    };
+    /** Chain mode settings */
+    chain?: {
+        enabled: boolean;
+        isLast: boolean;
+    };
+    /** Package manager name (e.g., "npm", "pnpm") */
+    packageManager?: string;
+    /** Base branch for rebase/PR (e.g., "main") */
+    baseBranch?: string;
+    /** Per-phase progress callback (used in parallel mode) */
+    onProgress?: ProgressCallback;
+}

package/dist/src/lib/workflow/types.js

@@ -1,6 +1,24 @@
 /**
  * Core types for workflow execution
  */
+import { z } from "zod";
+/**
+ * Canonical Zod schema for all workflow phases.
+ *
+ * This is the single source of truth — state-schema.ts and run-log-schema.ts
+ * both reference this definition. Add new phases here only.
+ */
+export const PhaseSchema = z.enum([
+    "spec",
+    "security-review",
+    "exec",
+    "testgen",
+    "test",
+    "verify",
+    "qa",
+    "loop",
+    "merger",
+]);
 /**
  * Default phases for workflow execution
  */
@@ -15,7 +33,8 @@ export const DEFAULT_CONFIG = {
     maxIterations: 3,
     skipVerification: false,
     sequential: false,
-    forceParallel: false,
+    concurrency: 3,
+    parallel: false,
     verbose: false,
     noSmartTests: false,
     dryRun: false,

package/dist/src/lib/workflow/worktree-discovery.d.ts

@@ -13,7 +13,7 @@
  * }
  * ```
  */
-import { type Phase } from "./state-schema.js";
+import { type Phase } from "./types.js";
 export interface DiscoverOptions {
     /** State file path (default: .sequant/state.json) */
     statePath?: string;

package/dist/src/lib/workflow/worktree-discovery.js

@@ -18,6 +18,7 @@ import * as path from "path";
 import { spawnSync } from "child_process";
 import { StateManager } from "./state-manager.js";
 import { RunLogSchema, LOG_PATHS } from "./run-log-schema.js";
+import { GitHubProvider } from "./platforms/github.js";
 /**
  * Parse issue number from a branch name
  *
@@ -44,25 +45,16 @@ function parseIssueNumberFromBranch(branch) {
     }
     return null;
 }
+/** Shared GitHubProvider instance for issue title lookups. */
+const ghProvider = new GitHubProvider();
 /**
- * Fetch issue title from GitHub using gh CLI
+ * Fetch issue title from GitHub using GitHubProvider.
  *
  * Returns placeholder if gh is not available or fetch fails.
  */
 function fetchIssueTitle(issueNumber) {
-    try {
-        const result = spawnSync("gh", ["issue", "view", String(issueNumber), "--json", "title", "-q", ".title"], { stdio: "pipe", timeout: 10000 });
-        if (result.status === 0 && result.stdout) {
-            const title = result.stdout.toString().trim();
-            if (title) {
-                return title;
-            }
-        }
-    }
-    catch {
-        // gh not available or error - use placeholder
-    }
-    return `(title unavailable for #${issueNumber})`;
+    return (ghProvider.fetchIssueTitleSync(String(issueNumber)) ??
+        `(title unavailable for #${issueNumber})`);
 }
 function getWorktreeDetails() {
     const result = spawnSync("git", ["worktree", "list", "--porcelain"], {