sequant 1.9.0 → 1.10.1

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

@@ -0,0 +1,190 @@
+/**
+ * Zod schemas for persistent workflow state tracking
+ *
+ * These schemas define the structure of `.sequant/state.json` which tracks
+ * the current state of all issues being processed through the workflow.
+ *
+ * @example
+ * ```typescript
+ * import { WorkflowStateSchema, type WorkflowState } from './state-schema';
+ *
+ * // Validate state file
+ * const state = WorkflowStateSchema.parse(JSON.parse(stateContent));
+ *
+ * // Type-safe access
+ * const issue42 = state.issues["42"];
+ * console.log(issue42.currentPhase, issue42.status);
+ * ```
+ */
+import { z } from "zod";
+/**
+ * Workflow phases in order of execution
+ */
+export const WORKFLOW_PHASES = [
+    "spec",
+    "security-review",
+    "exec",
+    "testgen",
+    "test",
+    "qa",
+    "loop",
+];
+/**
+ * Phase status - tracks individual phase progress
+ */
+export const PhaseStatusSchema = z.enum([
+    "pending", // Phase not yet started
+    "in_progress", // Phase currently executing
+    "completed", // Phase finished successfully
+    "failed", // Phase finished with errors
+    "skipped", // Phase intentionally skipped (e.g., bug labels skip spec)
+]);
+/**
+ * Issue status - tracks overall issue progress
+ */
+export const IssueStatusSchema = z.enum([
+    "not_started", // Issue tracked but no work begun
+    "in_progress", // Actively being worked on
+    "ready_for_merge", // All phases passed, PR ready for review
+    "merged", // PR merged, work complete
+    "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",
+    "qa",
+    "loop",
+]);
+/**
+ * Individual phase state within an issue
+ */
+export const PhaseStateSchema = z.object({
+    /** Current status of the phase */
+    status: PhaseStatusSchema,
+    /** When the phase started (if started) */
+    startedAt: z.string().datetime().optional(),
+    /** When the phase completed (if completed/failed/skipped) */
+    completedAt: z.string().datetime().optional(),
+    /** Error message if phase failed */
+    error: z.string().optional(),
+    /** Number of loop iterations (for loop phase) */
+    iteration: z.number().int().nonnegative().optional(),
+});
+/**
+ * PR information for an issue
+ */
+export const PRInfoSchema = z.object({
+    /** PR number */
+    number: z.number().int().positive(),
+    /** PR URL */
+    url: z.string().url(),
+});
+/**
+ * Quality loop state
+ */
+export const LoopStateSchema = z.object({
+    /** Whether quality loop is enabled */
+    enabled: z.boolean(),
+    /** Current iteration number */
+    iteration: z.number().int().nonnegative(),
+    /** Maximum iterations allowed */
+    maxIterations: z.number().int().positive(),
+});
+/**
+ * Complete state for a single issue
+ */
+export const IssueStateSchema = z.object({
+    /** GitHub issue number */
+    number: z.number().int().positive(),
+    /** Issue title */
+    title: z.string(),
+    /** Overall issue status */
+    status: IssueStatusSchema,
+    /** Path to the worktree (if created) */
+    worktree: z.string().optional(),
+    /** Branch name for this issue */
+    branch: z.string().optional(),
+    /** Current phase being executed or last executed */
+    currentPhase: PhaseSchema.optional(),
+    /** State of each phase (only phases that have been started/tracked) */
+    phases: z.record(z.string(), PhaseStateSchema),
+    /** PR information (if PR created) */
+    pr: PRInfoSchema.optional(),
+    /** Quality loop state (if loop enabled) */
+    loop: LoopStateSchema.optional(),
+    /** Claude session ID (for resume) */
+    sessionId: z.string().optional(),
+    /** Most recent activity timestamp */
+    lastActivity: z.string().datetime(),
+    /** When this issue was first tracked */
+    createdAt: z.string().datetime(),
+});
+/**
+ * Complete workflow state schema
+ *
+ * This is the top-level schema for `.sequant/state.json`
+ */
+export const WorkflowStateSchema = z.object({
+    /** Schema version for backwards compatibility */
+    version: z.literal(1),
+    /** When the state file was last updated */
+    lastUpdated: z.string().datetime(),
+    /** State for all tracked issues, keyed by issue number */
+    issues: z.record(z.string(), IssueStateSchema),
+});
+/**
+ * Default state file path
+ */
+export const STATE_FILE_PATH = ".sequant/state.json";
+/**
+ * Create an empty workflow state
+ */
+export function createEmptyState() {
+    return {
+        version: 1,
+        lastUpdated: new Date().toISOString(),
+        issues: {},
+    };
+}
+/**
+ * Create initial state for a new issue
+ */
+export function createIssueState(issueNumber, title, options) {
+    const now = new Date().toISOString();
+    return {
+        number: issueNumber,
+        title,
+        status: "not_started",
+        worktree: options?.worktree,
+        branch: options?.branch,
+        phases: {},
+        loop: options?.qualityLoop
+            ? {
+                enabled: true,
+                iteration: 0,
+                maxIterations: options?.maxIterations ?? 3,
+            }
+            : undefined,
+        lastActivity: now,
+        createdAt: now,
+    };
+}
+/**
+ * Create initial phase state
+ */
+export function createPhaseState(status = "pending") {
+    if (status === "in_progress") {
+        return {
+            status,
+            startedAt: new Date().toISOString(),
+        };
+    }
+    return { status };
+}

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

@@ -0,0 +1,66 @@
+/**
+ * State utilities for rebuilding and cleaning up workflow state
+ *
+ * @example
+ * ```typescript
+ * import { rebuildStateFromLogs, cleanupStaleEntries } from './state-utils';
+ *
+ * // Rebuild state from run logs
+ * await rebuildStateFromLogs();
+ *
+ * // Clean up orphaned entries
+ * const result = await cleanupStaleEntries({ dryRun: true });
+ * ```
+ */
+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>;
+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;
+}
+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 */
+    orphaned: number[];
+    /** Error message if failed */
+    error?: string;
+}
+/**
+ * Clean up stale and orphaned entries from workflow state
+ *
+ * - Removes issues with non-existent worktrees (orphaned)
+ * - Optionally removes old merged/abandoned issues
+ */
+export declare function cleanupStaleEntries(options?: CleanupOptions): Promise<CleanupResult>;

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

@@ -0,0 +1,243 @@
+/**
+ * State utilities for rebuilding and cleaning up workflow state
+ *
+ * @example
+ * ```typescript
+ * import { rebuildStateFromLogs, cleanupStaleEntries } from './state-utils';
+ *
+ * // Rebuild state from run logs
+ * await rebuildStateFromLogs();
+ *
+ * // Clean up orphaned entries
+ * const result = await cleanupStaleEntries({ dryRun: true });
+ * ```
+ */
+import * as fs from "fs";
+import * as path from "path";
+import { spawnSync } from "child_process";
+import { StateManager } from "./state-manager.js";
+import { createEmptyState, createIssueState, createPhaseState, } from "./state-schema.js";
+import { RunLogSchema, LOG_PATHS } from "./run-log-schema.js";
+/**
+ * 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 async function rebuildStateFromLogs(options = {}) {
+    const logPath = options.logPath ?? LOG_PATHS.project;
+    if (!fs.existsSync(logPath)) {
+        return {
+            success: false,
+            logsProcessed: 0,
+            issuesFound: 0,
+            error: `Log directory not found: ${logPath}`,
+        };
+    }
+    try {
+        // Find all log files
+        const files = fs.readdirSync(logPath).filter((f) => f.endsWith(".json"));
+        if (files.length === 0) {
+            return {
+                success: true,
+                logsProcessed: 0,
+                issuesFound: 0,
+            };
+        }
+        // Sort by timestamp (newest first)
+        files.sort().reverse();
+        // Build state from logs
+        const state = createEmptyState();
+        const issueMap = new Map();
+        for (const file of files) {
+            const filePath = path.join(logPath, file);
+            try {
+                const content = fs.readFileSync(filePath, "utf-8");
+                const logData = JSON.parse(content);
+                const log = RunLogSchema.safeParse(logData);
+                if (!log.success) {
+                    if (options.verbose) {
+                        console.log(`⚠️  Invalid log format: ${file}`);
+                    }
+                    continue;
+                }
+                const runLog = log.data;
+                // Process each issue in the log
+                for (const issueLog of runLog.issues) {
+                    // Skip if we already have newer data for this issue
+                    if (issueMap.has(issueLog.issueNumber)) {
+                        continue;
+                    }
+                    // Create issue state from log
+                    const issueState = createIssueState(issueLog.issueNumber, issueLog.title);
+                    // Determine status from log
+                    if (issueLog.status === "success") {
+                        issueState.status = "ready_for_merge";
+                    }
+                    else if (issueLog.status === "failure") {
+                        issueState.status = "in_progress";
+                    }
+                    else {
+                        issueState.status = "in_progress";
+                    }
+                    // Add phase states from log
+                    for (const phaseLog of issueLog.phases) {
+                        const phaseState = createPhaseState(phaseLog.status === "success"
+                            ? "completed"
+                            : phaseLog.status === "failure"
+                                ? "failed"
+                                : phaseLog.status === "skipped"
+                                    ? "skipped"
+                                    : "completed");
+                        phaseState.startedAt = phaseLog.startTime;
+                        phaseState.completedAt = phaseLog.endTime;
+                        if (phaseLog.error) {
+                            phaseState.error = phaseLog.error;
+                        }
+                        issueState.phases[phaseLog.phase] = phaseState;
+                        // Update current phase to last executed
+                        issueState.currentPhase = phaseLog.phase;
+                    }
+                    // Set last activity from most recent phase
+                    const lastPhase = issueLog.phases[issueLog.phases.length - 1];
+                    if (lastPhase) {
+                        issueState.lastActivity = lastPhase.endTime;
+                    }
+                    issueMap.set(issueLog.issueNumber, issueState);
+                }
+                if (options.verbose) {
+                    console.log(`✓ Processed: ${file}`);
+                }
+            }
+            catch (err) {
+                if (options.verbose) {
+                    console.log(`⚠️  Error reading ${file}: ${err}`);
+                }
+            }
+        }
+        // Copy issues to state
+        for (const [num, issueState] of issueMap) {
+            state.issues[String(num)] = issueState;
+        }
+        // Save rebuilt state
+        const manager = new StateManager({
+            statePath: options.statePath,
+            verbose: options.verbose,
+        });
+        await manager.saveState(state);
+        return {
+            success: true,
+            logsProcessed: files.length,
+            issuesFound: issueMap.size,
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            logsProcessed: 0,
+            issuesFound: 0,
+            error: String(error),
+        };
+    }
+}
+/**
+ * Clean up stale and orphaned entries from workflow state
+ *
+ * - Removes issues with non-existent worktrees (orphaned)
+ * - Optionally removes 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: [],
+        };
+    }
+    try {
+        const state = await manager.getState();
+        const removed = [];
+        const orphaned = [];
+        // 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)) {
+                orphaned.push(issueNum);
+                if (options.verbose) {
+                    console.log(`🗑️  Orphaned: #${issueNum} (worktree not found: ${issueState.worktree})`);
+                }
+                if (!options.dryRun) {
+                    // Mark as abandoned or remove based on status
+                    if (issueState.status === "merged" ||
+                        issueState.status === "abandoned") {
+                        removed.push(issueNum);
+                        delete state.issues[issueNumStr];
+                    }
+                    else {
+                        // Update status to indicate orphaned state
+                        issueState.status = "abandoned";
+                    }
+                }
+                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,
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            removed: [],
+            orphaned: [],
+            error: String(error),
+        };
+    }
+}
+/**
+ * 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;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sequant",
-  "version": "1.9.0",
+  "version": "1.10.1",
   "description": "Quantize your development workflow - Sequential AI phases with quality gates",
   "type": "module",
   "bin": {

package/templates/scripts/new-feature.sh

@@ -1,9 +1,10 @@
 #!/bin/bash
 
 # Create a new feature worktree from a GitHub issue
-# Usage: ./scripts/new-feature.sh <issue-number> [--stash]
+# Usage: ./scripts/new-feature.sh <issue-number> [--base <branch>] [--stash]
 # Example: ./scripts/new-feature.sh 4
 # Example: ./scripts/new-feature.sh 4 --stash  # Auto-stash uncommitted changes
+# Example: ./scripts/new-feature.sh 4 --base feature/dashboard  # Branch from feature branch
 
 set -e
 
@@ -14,20 +15,27 @@ BLUE='\033[0;34m'
 YELLOW='\033[1;33m'
 NC='\033[0m' # No Color
 
-# Parse arguments (flexible position for --stash flag)
+# Parse arguments (flexible position for flags)
 STASH_FLAG=false
 ISSUE_NUMBER=""
+BASE_BRANCH="main"
 
-for arg in "$@"; do
-    case $arg in
+while [[ $# -gt 0 ]]; do
+    case $1 in
         --stash)
             STASH_FLAG=true
+            shift
+            ;;
+        --base)
+            BASE_BRANCH="$2"
+            shift 2
             ;;
         *)
             # First non-flag argument is the issue number
             if [ -z "$ISSUE_NUMBER" ]; then
-                ISSUE_NUMBER=$arg
+                ISSUE_NUMBER=$1
             fi
+            shift
             ;;
     esac
 done
@@ -35,9 +43,10 @@ done
 # Check if issue number is provided
 if [ -z "$ISSUE_NUMBER" ]; then
     echo -e "${RED}❌ Error: Issue number required${NC}"
-    echo "Usage: ./scripts/new-feature.sh <issue-number> [--stash]"
+    echo "Usage: ./scripts/new-feature.sh <issue-number> [--base <branch>] [--stash]"
     echo "Example: ./scripts/new-feature.sh 4"
     echo "Example: ./scripts/new-feature.sh 4 --stash"
+    echo "Example: ./scripts/new-feature.sh 4 --base feature/dashboard"
     exit 1
 fi
 
@@ -95,6 +104,7 @@ WORKTREE_DIR="../worktrees/${BRANCH_NAME}"
 
 echo -e "${GREEN}✨ Creating worktree for issue #${ISSUE_NUMBER}${NC}"
 echo -e "${BLUE}Branch: ${BRANCH_NAME}${NC}"
+echo -e "${BLUE}Base: ${BASE_BRANCH}${NC}"
 echo -e "${BLUE}Worktree: ${WORKTREE_DIR}${NC}"
 echo ""
 
@@ -132,14 +142,14 @@ if git show-ref --verify --quiet "refs/heads/${BRANCH_NAME}"; then
     fi
 fi
 
-# Update main branch
-echo -e "${BLUE}📥 Updating main branch...${NC}"
-git fetch origin main
-git checkout main
-git pull origin main
+# Update base branch
+echo -e "${BLUE}📥 Updating ${BASE_BRANCH} branch...${NC}"
+git fetch origin "$BASE_BRANCH"
+git checkout "$BASE_BRANCH"
+git pull origin "$BASE_BRANCH"
 
-# Create worktree
-echo -e "${BLUE}🌿 Creating new worktree...${NC}"
+# Create worktree from base branch
+echo -e "${BLUE}🌿 Creating new worktree from ${BASE_BRANCH}...${NC}"
 git worktree add "$WORKTREE_DIR" -b "$BRANCH_NAME"
 
 # Navigate to worktree