sequant 2.0.0 → 2.1.0

package/dist/src/lib/worktree-isolation.js

@@ -0,0 +1,310 @@
+/**
+ * Worktree isolation for parallel /exec agent groups.
+ *
+ * Provides sub-worktree creation, merge-back, and cleanup for
+ * parallel agent execution, eliminating file conflicts structurally.
+ *
+ * @see https://github.com/sequant-io/sequant/issues/485
+ */
+import { execSync } from "child_process";
+import { existsSync, mkdirSync, symlinkSync, copyFileSync, readFileSync, readdirSync, rmdirSync, } from "fs";
+import { join, basename, dirname } from "path";
+/**
+ * Directory name for sub-worktrees inside the issue worktree.
+ * This directory is nested inside the issue worktree for locality.
+ */
+export const SUB_WORKTREE_DIR = ".exec-agents";
+/**
+ * Default files to copy into sub-worktrees when no .worktreeinclude exists.
+ * Matches the pattern in scripts/dev/new-feature.sh.
+ */
+const DEFAULT_INCLUDE_FILES = [
+    ".env",
+    ".env.local",
+    ".env.development",
+    ".claude/settings.local.json",
+];
+/** Name of the worktree include file */
+export const WORKTREE_INCLUDE_FILE = ".worktreeinclude";
+/**
+ * Read the list of files to copy into sub-worktrees.
+ *
+ * Reads from .worktreeinclude if it exists (one path per line, # comments),
+ * otherwise returns the hardcoded default list.
+ */
+export function getIncludeFiles(worktreePath) {
+    const includeFile = join(worktreePath, WORKTREE_INCLUDE_FILE);
+    if (!existsSync(includeFile)) {
+        return DEFAULT_INCLUDE_FILES;
+    }
+    try {
+        return readFileSync(includeFile, "utf-8")
+            .split("\n")
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0 && !line.startsWith("#"));
+    }
+    catch {
+        return DEFAULT_INCLUDE_FILES;
+    }
+}
+/**
+ * Run a git command and return stdout, trimmed.
+ * Throws on non-zero exit code.
+ */
+function git(args, cwd) {
+    return execSync(`git ${args}`, {
+        cwd,
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+}
+/**
+ * Run a git command and return success/failure without throwing.
+ */
+function gitSafe(args, cwd) {
+    try {
+        const stdout = execSync(`git ${args}`, {
+            cwd,
+            encoding: "utf-8",
+            stdio: ["pipe", "pipe", "pipe"],
+        }).trim();
+        return { success: true, stdout, stderr: "" };
+    }
+    catch (err) {
+        const error = err;
+        return {
+            success: false,
+            stdout: error.stdout ?? "",
+            stderr: error.stderr ?? "",
+        };
+    }
+}
+/**
+ * Generate a branch name for a sub-worktree agent.
+ *
+ * @param issueWorktreePath - Path to the issue worktree
+ * @param agentIndex - Zero-based agent index
+ * @returns Branch name like `exec-agent-485-0`
+ */
+export function agentBranchName(issueWorktreePath, agentIndex) {
+    // Extract issue number from worktree path
+    const dirName = basename(issueWorktreePath);
+    const issueMatch = dirName.match(/^(\d+)-/);
+    const issueNum = issueMatch ? issueMatch[1] : dirName.slice(0, 10);
+    return `exec-agent-${issueNum}-${agentIndex}`;
+}
+/**
+ * Create a sub-worktree for a parallel agent.
+ *
+ * The sub-worktree is created inside the issue worktree at
+ * `.exec-agents/agent-<N>/` and branches from the issue branch HEAD.
+ *
+ * node_modules is symlinked from the issue worktree for speed.
+ * Environment files are copied per new-feature.sh convention.
+ *
+ * @param issueWorktreePath - Absolute path to the issue worktree
+ * @param agentIndex - Zero-based agent index
+ * @returns Sub-worktree info, or null if creation failed
+ */
+export function createSubWorktree(issueWorktreePath, agentIndex) {
+    const branch = agentBranchName(issueWorktreePath, agentIndex);
+    const subDir = join(issueWorktreePath, SUB_WORKTREE_DIR);
+    const agentPath = join(subDir, `agent-${agentIndex}`);
+    try {
+        // Ensure .exec-agents directory exists
+        if (!existsSync(subDir)) {
+            mkdirSync(subDir, { recursive: true });
+        }
+        // Create worktree branching from current HEAD
+        git(`worktree add "${agentPath}" -b ${branch}`, issueWorktreePath);
+        // Symlink node_modules from issue worktree (fast: ~13ms)
+        const issueNodeModules = join(issueWorktreePath, "node_modules");
+        const agentNodeModules = join(agentPath, "node_modules");
+        if (existsSync(issueNodeModules) && !existsSync(agentNodeModules)) {
+            symlinkSync(issueNodeModules, agentNodeModules);
+        }
+        // Copy files listed in .worktreeinclude (AC-7)
+        const includeFiles = getIncludeFiles(issueWorktreePath);
+        for (const filePath of includeFiles) {
+            const src = join(issueWorktreePath, filePath);
+            if (existsSync(src)) {
+                const dest = join(agentPath, filePath);
+                const destDir = dirname(dest);
+                if (!existsSync(destDir)) {
+                    mkdirSync(destDir, { recursive: true });
+                }
+                copyFileSync(src, dest);
+            }
+        }
+        return { path: agentPath, branch, agentIndex };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(`Failed to create sub-worktree for agent ${agentIndex}: ${message}`);
+        return null;
+    }
+}
+/**
+ * Merge a single sub-worktree's changes back into the issue worktree.
+ *
+ * Uses `git merge --no-ff` for built-in conflict detection.
+ *
+ * @param issueWorktreePath - Absolute path to the issue worktree
+ * @param subWorktree - Sub-worktree info
+ * @returns Merge result with conflict details if any
+ */
+export function mergeBackSubWorktree(issueWorktreePath, subWorktree) {
+    const { branch, agentIndex } = subWorktree;
+    // Check if the agent branch has any commits beyond the base
+    const hasChanges = gitSafe(`log ${branch} --not HEAD --oneline`, issueWorktreePath);
+    if (hasChanges.success && hasChanges.stdout.length === 0) {
+        return { success: true, branch, agentIndex, conflictFiles: [] };
+    }
+    // Attempt merge
+    const mergeResult = gitSafe(`merge --no-ff ${branch} -m "Merge exec-agent-${agentIndex}"`, issueWorktreePath);
+    if (mergeResult.success) {
+        return { success: true, branch, agentIndex, conflictFiles: [] };
+    }
+    // Merge failed — detect conflict files
+    const conflictResult = gitSafe("diff --name-only --diff-filter=U", issueWorktreePath);
+    const conflictFiles = conflictResult.stdout
+        .split("\n")
+        .filter((f) => f.length > 0);
+    // Abort the failed merge to leave clean state
+    gitSafe("merge --abort", issueWorktreePath);
+    return {
+        success: false,
+        branch,
+        agentIndex,
+        conflictFiles,
+        error: `Merge conflict in ${conflictFiles.length} file(s): ${conflictFiles.join(", ")}`,
+    };
+}
+/**
+ * Merge all sub-worktrees back into the issue worktree.
+ *
+ * Merges are attempted sequentially. If one conflicts, the merge is
+ * aborted and subsequent agents are still attempted. Non-conflicting
+ * changes are preserved in the issue worktree.
+ *
+ * @param issueWorktreePath - Absolute path to the issue worktree
+ * @param subWorktrees - Array of sub-worktree info
+ * @returns Aggregate merge result
+ */
+export function mergeAllSubWorktrees(issueWorktreePath, subWorktrees) {
+    const results = [];
+    let merged = 0;
+    let conflicts = 0;
+    for (const sub of subWorktrees) {
+        const result = mergeBackSubWorktree(issueWorktreePath, sub);
+        results.push(result);
+        if (result.success) {
+            merged++;
+        }
+        else {
+            conflicts++;
+        }
+    }
+    return { merged, conflicts, results };
+}
+/**
+ * Remove a single sub-worktree and its branch.
+ *
+ * @param issueWorktreePath - Absolute path to the issue worktree
+ * @param subWorktree - Sub-worktree info to clean up
+ */
+export function cleanupSubWorktree(issueWorktreePath, subWorktree) {
+    const { path: subPath, branch } = subWorktree;
+    // Remove worktree
+    if (existsSync(subPath)) {
+        gitSafe(`worktree remove "${subPath}" --force`, issueWorktreePath);
+    }
+    // Delete branch
+    gitSafe(`branch -D ${branch}`, issueWorktreePath);
+}
+/**
+ * Clean up all sub-worktrees for an issue worktree.
+ *
+ * Handles both successful cleanup and orphaned worktrees from
+ * interrupted sessions.
+ *
+ * @param issueWorktreePath - Absolute path to the issue worktree
+ * @param subWorktrees - Known sub-worktrees to clean (if provided)
+ */
+export function cleanupAllSubWorktrees(issueWorktreePath, subWorktrees) {
+    if (subWorktrees) {
+        for (const sub of subWorktrees) {
+            cleanupSubWorktree(issueWorktreePath, sub);
+        }
+    }
+    // Also clean any orphaned sub-worktrees from interrupted sessions
+    cleanupOrphanedSubWorktrees(issueWorktreePath);
+}
+/**
+ * Detect and clean up orphaned sub-worktrees from interrupted sessions.
+ *
+ * Scans the `.exec-agents/` directory for any remaining worktrees and
+ * removes them. Also prunes stale worktree entries from git.
+ *
+ * @param issueWorktreePath - Absolute path to the issue worktree
+ */
+export function cleanupOrphanedSubWorktrees(issueWorktreePath) {
+    const subDir = join(issueWorktreePath, SUB_WORKTREE_DIR);
+    if (!existsSync(subDir)) {
+        return;
+    }
+    // Prune stale worktree entries
+    gitSafe("worktree prune", issueWorktreePath);
+    // List worktrees to find any still pointing to .exec-agents/
+    const listResult = gitSafe("worktree list --porcelain", issueWorktreePath);
+    if (!listResult.success)
+        return;
+    const lines = listResult.stdout.split("\n");
+    for (const line of lines) {
+        if (line.startsWith("worktree ") && line.includes(SUB_WORKTREE_DIR)) {
+            const worktreePath = line.replace("worktree ", "");
+            gitSafe(`worktree remove "${worktreePath}" --force`, issueWorktreePath);
+        }
+    }
+    // Clean up orphaned exec-agent branches
+    const branchResult = gitSafe("branch --list exec-agent-*", issueWorktreePath);
+    if (branchResult.success && branchResult.stdout.length > 0) {
+        const branches = branchResult.stdout
+            .split("\n")
+            .map((b) => b.trim())
+            .filter((b) => b.length > 0);
+        for (const branch of branches) {
+            gitSafe(`branch -D ${branch}`, issueWorktreePath);
+        }
+    }
+    // Remove the .exec-agents directory if empty
+    try {
+        const entries = readdirSync(subDir);
+        if (entries.length === 0) {
+            rmdirSync(subDir);
+        }
+    }
+    catch {
+        // Ignore errors during directory cleanup
+    }
+}
+/**
+ * Format merge-back results for logging.
+ *
+ * @param result - Aggregate merge result
+ * @returns Human-readable summary
+ */
+export function formatMergeResult(result) {
+    const lines = [];
+    const total = result.merged + result.conflicts;
+    lines.push(`Merge-back: ${result.merged}/${total} agents merged successfully`);
+    if (result.conflicts > 0) {
+        lines.push(`Conflicts: ${result.conflicts} agent(s) had merge conflicts`);
+        for (const r of result.results) {
+            if (!r.success) {
+                lines.push(`  Agent ${r.agentIndex}: ${r.error}`);
+            }
+        }
+    }
+    return lines.join("\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sequant",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Quantize your development workflow - Sequential AI phases with quality gates",
   "type": "module",
   "bin": {
@@ -32,16 +32,26 @@
     "prepublishOnly": "npm run build"
   },
   "keywords": [
+    "ai",
     "claude",
     "claude-code",
+    "aider",
+    "mcp",
+    "cli",
     "workflow",
-    "ai",
     "automation",
-    "quality",
-    "sequential",
-    "agent-skills",
-    "cursor",
-    "vscode"
+    "coding-agent",
+    "agent",
+    "github",
+    "github-issues",
+    "quality-gates",
+    "code-quality",
+    "orchestrator",
+    "developer-tools",
+    "anthropic",
+    "llm",
+    "ai-coding",
+    "copilot"
   ],
   "author": "Sequant Contributors",
   "license": "MIT",
@@ -54,7 +64,7 @@
   },
   "homepage": "https://sequant.io",
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=20.19.0"
   },
   "peerDependencies": {
     "@modelcontextprotocol/sdk": "^1.27.1"
@@ -83,17 +93,17 @@
     "zod": "^4.3.5"
   },
   "devDependencies": {
-    "@eslint/js": "^9.39.2",
+    "@eslint/js": "^10.0.1",
     "@types/gradient-string": "^1.1.6",
     "@types/inquirer": "^9.0.7",
     "@types/node": "^25.4.0",
-    "@typescript-eslint/eslint-plugin": "^8.52.0",
-    "@typescript-eslint/parser": "^8.52.0",
-    "eslint": "^9.39.2",
+    "@typescript-eslint/eslint-plugin": "^8.58.0",
+    "@typescript-eslint/parser": "^8.58.0",
+    "eslint": "^10.1.0",
     "globals": "^17.0.0",
     "tsx": "^4.19.2",
-    "typescript": "^5.7.2",
-    "typescript-eslint": "^8.52.0",
+    "typescript": "^6.0.2",
+    "typescript-eslint": "^8.58.0",
     "vitest": "^4.1.0"
   }
 }

package/templates/agents/sequant-explorer.md

@@ -0,0 +1,23 @@
+---
+name: sequant-explorer
+description: Codebase exploration agent for sequant /spec phase. Searches for existing patterns, components, database schemas, and file structures. Use when gathering context before planning a feature implementation.
+model: haiku
+maxTurns: 15
+tools:
+  - Read
+  - Grep
+  - Glob
+---
+
+You are an exploration agent for the sequant development workflow.
+
+Your job is to search the codebase for existing patterns, components, and structures relevant to a planned feature.
+
+Rules:
+- Search thoroughly across relevant directories
+- Report findings in structured format: file paths, patterns discovered, recommendations
+- Do NOT modify any files
+- Do NOT run shell commands
+- Send results back via SendMessage when complete
+- All grep commands must use `|| true` to prevent exit code 1 on zero matches
+- Focus on actionable findings that inform implementation decisions

package/templates/agents/sequant-implementer.md

@@ -0,0 +1,18 @@
+---
+name: sequant-implementer
+description: Implementation agent for sequant /exec parallel groups. Handles component creation, type definitions, CLI scripts, and refactoring tasks. Use when spawned by the /exec skill to implement a specific subtask in a feature worktree.
+permissionMode: bypassPermissions
+maxTurns: 25
+---
+
+You are an implementation agent for the sequant development workflow.
+
+Your job is to implement a specific subtask as described in your prompt, working within a feature worktree.
+
+Rules:
+- Work ONLY in the worktree path specified in your prompt
+- Do NOT create test files unless explicitly asked
+- Do NOT push to remote or create PRs
+- Report what files were created/modified when complete via SendMessage
+- Follow existing codebase patterns and conventions
+- All grep commands must use `|| true` to prevent exit code 1 on zero matches

package/templates/agents/sequant-qa-checker.md

@@ -0,0 +1,24 @@
+---
+name: sequant-qa-checker
+description: Quality check agent for sequant /qa phase. Runs type safety, scope/size, security, and documentation checks on diffs. Use when spawned by the /qa skill to perform parallel or sequential quality checks.
+model: haiku
+permissionMode: bypassPermissions
+effort: low
+maxTurns: 15
+tools:
+  - Read
+  - Grep
+  - Glob
+  - Bash
+---
+
+You are a quality check agent for the sequant development workflow.
+
+Your job is to run a specific quality check on a code diff and report results concisely.
+
+Rules:
+- Run only the check described in your prompt
+- Report results in structured format: check name, pass/fail, issue count, details
+- Send results back via SendMessage when complete
+- Do not modify any files
+- All grep commands must use `|| true` to prevent exit code 1 on zero matches

package/templates/agents/sequant-testgen.md

@@ -0,0 +1,25 @@
+---
+name: sequant-testgen
+description: Test stub generator for sequant /testgen phase. Parses verification criteria from /spec comments and generates Jest/Vitest test stubs with Given/When/Then structure. Use when spawned by the /testgen skill.
+model: haiku
+maxTurns: 25
+tools:
+  - Read
+  - Grep
+  - Glob
+  - Write
+---
+
+You are a test stub generation agent for the sequant development workflow.
+
+Your job is to parse verification criteria and generate test stubs following project conventions.
+
+Rules:
+- Generate test stubs using the project's test framework (Jest or Vitest)
+- Include Given/When/Then comments in each test
+- Add TODO markers where implementation is needed
+- Use `throw new Error('Test stub - implement this test')` for unimplemented tests
+- Include failure path stubs based on the action verb
+- Do NOT run shell commands
+- Send results back via SendMessage when complete
+- Return ONLY the test code, no explanation

package/templates/scripts/cleanup-worktree.sh

@@ -53,6 +53,24 @@ if [ "$PR_STATUS" != "MERGED" ]; then
     fi
 fi
 
+# Clean up any exec-agent sub-worktrees first (from parallel isolation)
+EXEC_AGENTS_DIR="$WORKTREE_PATH/.exec-agents"
+if [ -d "$EXEC_AGENTS_DIR" ]; then
+    echo -e "${BLUE}🧹 Cleaning up exec-agent sub-worktrees...${NC}"
+    for agent_dir in "$EXEC_AGENTS_DIR"/agent-*; do
+        if [ -d "$agent_dir" ]; then
+            echo -e "${BLUE}   Removing: $(basename "$agent_dir")${NC}"
+            git worktree remove "$agent_dir" --force 2>/dev/null || true
+        fi
+    done
+    # Clean up orphaned exec-agent branches
+    git branch --list 'exec-agent-*' 2>/dev/null | while read -r branch; do
+        branch=$(echo "$branch" | tr -d ' *')
+        git branch -D "$branch" 2>/dev/null || true
+    done
+    rmdir "$EXEC_AGENTS_DIR" 2>/dev/null || true
+fi
+
 # Remove worktree
 echo -e "${BLUE}📂 Removing worktree...${NC}"
 git worktree remove "$WORKTREE_PATH" --force