sequant 1.16.0 → 1.17.0

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

@@ -0,0 +1,61 @@
+/**
+ * Worktree discovery for state bootstrapping
+ *
+ * @module worktree-discovery
+ * @example
+ * ```typescript
+ * import { discoverUntrackedWorktrees } from './worktree-discovery';
+ *
+ * // Discover worktrees not yet tracked in state
+ * const result = await discoverUntrackedWorktrees({ verbose: true });
+ * for (const worktree of result.discovered) {
+ *   console.log(`Found: #${worktree.issueNumber} - ${worktree.title}`);
+ * }
+ * ```
+ */
+import { type Phase } from "./state-schema.js";
+export interface DiscoverOptions {
+    /** State file path (default: .sequant/state.json) */
+    statePath?: string;
+    /** Enable verbose logging */
+    verbose?: boolean;
+}
+export interface DiscoveredWorktree {
+    /** Issue number extracted from branch name */
+    issueNumber: number;
+    /** Issue title (fetched from GitHub or placeholder) */
+    title: string;
+    /** Full path to the worktree */
+    worktreePath: string;
+    /** Branch name */
+    branch: string;
+    /** Inferred current phase from logs (if available) */
+    inferredPhase?: Phase;
+}
+export interface SkippedWorktree {
+    /** Path to the worktree */
+    path: string;
+    /** Reason it was skipped */
+    reason: string;
+}
+export interface DiscoverResult {
+    /** Whether discovery was successful */
+    success: boolean;
+    /** Number of worktrees scanned */
+    worktreesScanned: number;
+    /** Number of worktrees already tracked */
+    alreadyTracked: number;
+    /** Discovered worktrees not yet in state */
+    discovered: DiscoveredWorktree[];
+    /** Worktrees that were skipped (not matching pattern, etc.) */
+    skipped: SkippedWorktree[];
+    /** Error message if failed */
+    error?: string;
+}
+/**
+ * Discover worktrees that are not yet tracked in state
+ *
+ * Scans all git worktrees, identifies those with issue-related branch names,
+ * and returns information about worktrees not yet in the state file.
+ */
+export declare function discoverUntrackedWorktrees(options?: DiscoverOptions): Promise<DiscoverResult>;

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

@@ -0,0 +1,229 @@
+/**
+ * Worktree discovery for state bootstrapping
+ *
+ * @module worktree-discovery
+ * @example
+ * ```typescript
+ * import { discoverUntrackedWorktrees } from './worktree-discovery';
+ *
+ * // Discover worktrees not yet tracked in state
+ * const result = await discoverUntrackedWorktrees({ verbose: true });
+ * for (const worktree of result.discovered) {
+ *   console.log(`Found: #${worktree.issueNumber} - ${worktree.title}`);
+ * }
+ * ```
+ */
+import * as fs from "fs";
+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";
+/**
+ * Parse issue number from a branch name
+ *
+ * Supports patterns:
+ * - feature/<number>-<slug>
+ * - issue-<number>
+ * - <number>-<slug>
+ */
+function parseIssueNumberFromBranch(branch) {
+    // Pattern: feature/123-description or feature/123
+    const featureMatch = branch.match(/^feature\/(\d+)(?:-|$)/);
+    if (featureMatch) {
+        return parseInt(featureMatch[1], 10);
+    }
+    // Pattern: issue-123
+    const issueMatch = branch.match(/^issue-(\d+)$/);
+    if (issueMatch) {
+        return parseInt(issueMatch[1], 10);
+    }
+    // Pattern: 123-description (bare number prefix)
+    const bareMatch = branch.match(/^(\d+)-/);
+    if (bareMatch) {
+        return parseInt(bareMatch[1], 10);
+    }
+    return null;
+}
+/**
+ * Fetch issue title from GitHub using gh CLI
+ *
+ * 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})`;
+}
+function getWorktreeDetails() {
+    const result = spawnSync("git", ["worktree", "list", "--porcelain"], {
+        stdio: "pipe",
+    });
+    if (result.status !== 0) {
+        return [];
+    }
+    const output = result.stdout.toString();
+    const worktrees = [];
+    let current = {};
+    for (const line of output.split("\n")) {
+        if (line.startsWith("worktree ")) {
+            // Start of new worktree entry
+            if (current.path) {
+                worktrees.push(current);
+            }
+            current = { path: line.substring(9) };
+        }
+        else if (line.startsWith("HEAD ")) {
+            current.head = line.substring(5);
+        }
+        else if (line.startsWith("branch refs/heads/")) {
+            current.branch = line.substring(18);
+        }
+        else if (line === "" && current.path) {
+            // End of entry
+            worktrees.push(current);
+            current = {};
+        }
+    }
+    // Don't forget the last entry
+    if (current.path && current.branch) {
+        worktrees.push(current);
+    }
+    return worktrees;
+}
+/**
+ * Infer the current phase for an issue by checking logs
+ */
+function inferPhaseFromLogs(issueNumber) {
+    const logPath = LOG_PATHS.project;
+    if (!fs.existsSync(logPath)) {
+        return undefined;
+    }
+    try {
+        const files = fs.readdirSync(logPath).filter((f) => f.endsWith(".json"));
+        // Sort by timestamp (newest first)
+        files.sort().reverse();
+        for (const file of files) {
+            try {
+                const content = fs.readFileSync(path.join(logPath, file), "utf-8");
+                const logData = JSON.parse(content);
+                const log = RunLogSchema.safeParse(logData);
+                if (!log.success)
+                    continue;
+                // Find this issue in the log
+                const issueLog = log.data.issues.find((i) => i.issueNumber === issueNumber);
+                if (issueLog && issueLog.phases.length > 0) {
+                    // Return the last executed phase
+                    const lastPhase = issueLog.phases[issueLog.phases.length - 1];
+                    return lastPhase.phase;
+                }
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    catch {
+        return undefined;
+    }
+    return undefined;
+}
+/**
+ * Discover worktrees that are not yet tracked in state
+ *
+ * Scans all git worktrees, identifies those with issue-related branch names,
+ * and returns information about worktrees not yet in the state file.
+ */
+export async function discoverUntrackedWorktrees(options = {}) {
+    try {
+        const worktrees = getWorktreeDetails();
+        const discovered = [];
+        const skipped = [];
+        let alreadyTracked = 0;
+        // Get existing state
+        const manager = new StateManager({
+            statePath: options.statePath,
+            verbose: options.verbose,
+        });
+        const state = await manager.getState();
+        const trackedIssues = new Set(Object.keys(state.issues).map((n) => parseInt(n, 10)));
+        for (const worktree of worktrees) {
+            // Skip if no branch (detached HEAD)
+            if (!worktree.branch) {
+                skipped.push({
+                    path: worktree.path,
+                    reason: "detached HEAD (no branch)",
+                });
+                continue;
+            }
+            // Skip main/master branches
+            if (worktree.branch === "main" || worktree.branch === "master") {
+                skipped.push({
+                    path: worktree.path,
+                    reason: "main/master branch (not a feature worktree)",
+                });
+                continue;
+            }
+            // Try to parse issue number from branch
+            const issueNumber = parseIssueNumberFromBranch(worktree.branch);
+            if (issueNumber === null) {
+                skipped.push({
+                    path: worktree.path,
+                    reason: `branch name doesn't match issue pattern: ${worktree.branch}`,
+                });
+                continue;
+            }
+            // Check if already tracked
+            if (trackedIssues.has(issueNumber)) {
+                alreadyTracked++;
+                if (options.verbose) {
+                    console.log(`  Already tracked: #${issueNumber} (${worktree.branch})`);
+                }
+                continue;
+            }
+            // Fetch title from GitHub
+            if (options.verbose) {
+                console.log(`  Fetching title for #${issueNumber}...`);
+            }
+            const title = fetchIssueTitle(issueNumber);
+            // Try to infer phase from logs
+            const inferredPhase = inferPhaseFromLogs(issueNumber);
+            discovered.push({
+                issueNumber,
+                title,
+                worktreePath: worktree.path,
+                branch: worktree.branch,
+                inferredPhase,
+            });
+            if (options.verbose) {
+                console.log(`  Discovered: #${issueNumber} - ${title}${inferredPhase ? ` (phase: ${inferredPhase})` : ""}`);
+            }
+        }
+        return {
+            success: true,
+            worktreesScanned: worktrees.length,
+            alreadyTracked,
+            discovered,
+            skipped,
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            worktreesScanned: 0,
+            alreadyTracked: 0,
+            discovered: [],
+            skipped: [],
+            error: String(error),
+        };
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sequant",
-  "version": "1.16.0",
+  "version": "1.17.0",
   "description": "Quantize your development workflow - Sequential AI phases with quality gates",
   "type": "module",
   "bin": {
@@ -50,7 +50,7 @@
   "bugs": {
     "url": "https://github.com/sequant-io/sequant/issues"
   },
-  "homepage": "https://github.com/sequant-io/sequant#readme",
+  "homepage": "https://sequant.io",
   "engines": {
     "node": ">=18.0.0"
   },
@@ -62,9 +62,9 @@
     "chokidar": "^5.0.0",
     "cli-table3": "^0.6.5",
     "commander": "^12.1.0",
-    "diff": "^7.0.0",
+    "diff": "^8.0.3",
     "gradient-string": "^3.0.0",
-    "hono": "^4.11.4",
+    "hono": "^4.12.1",
     "inquirer": "^12.3.2",
     "open": "^11.0.0",
     "ora": "^8.2.0",
@@ -73,7 +73,6 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.39.2",
-    "@types/diff": "^7.0.0",
     "@types/gradient-string": "^1.1.6",
     "@types/inquirer": "^9.0.7",
     "@types/node": "^22.10.5",

package/templates/skills/exec/SKILL.md

@@ -64,7 +64,7 @@ When invoked as `/exec`, your job is to:
 ```bash
 # Check for existing phase markers
 phase_data=$(gh issue view <issue-number> --json comments --jq '[.comments[].body]' | \
-  grep -o '{[^}]*}' | grep '"phase"' | tail -1)
+  grep -o '{[^}]*}' | grep '"phase"' | tail -1 || true)
 
 if [[ -n "$phase_data" ]]; then
   phase=$(echo "$phase_data" | jq -r '.phase')
@@ -127,7 +127,7 @@ git log --oneline -3 --stat
 
 # Check for existing PRs or branches for this issue
 gh pr list --search "<issue-number>"
-git branch -a | grep -i "<issue-number>"
+git branch -a | grep -i "<issue-number>" || true
 ```
 
 **Why this matters:** After context restoration, PRs may have merged, branches may have changed, or work may already be complete. Always verify before creating duplicate work.

package/templates/skills/fullsolve/SKILL.md

@@ -97,7 +97,7 @@ When invoked as `/fullsolve <issue-number>`, execute the complete issue resoluti
 ```bash
 # Get all phase markers from issue comments
 comments_json=$(gh issue view <issue-number> --json comments --jq '[.comments[].body]')
-markers=$(echo "$comments_json" | grep -o '{[^}]*}' | grep '"phase"')
+markers=$(echo "$comments_json" | grep -o '{[^}]*}' | grep '"phase"' || true)
 
 if [[ -n "$markers" ]]; then
   echo "Phase markers detected:"
@@ -147,7 +147,7 @@ When posting progress comments after each phase, append the appropriate marker:
 git log --oneline -5 --stat
 
 # Check for any existing work on this issue
-git branch -a | grep -i "<issue-number>"
+git branch -a | grep -i "<issue-number>" || true
 gh pr list --search "<issue-number>"
 ```
 
@@ -345,10 +345,10 @@ while test_iteration < 3:
 
 ```bash
 # Type safety
-git diff main...HEAD | grep -E ":\s*any[,)]|as any"
+git diff main...HEAD | grep -E ":\s*any[,)]|as any" || true
 
 # Deleted tests
-git diff main...HEAD --diff-filter=D --name-only | grep -E "\.test\."
+git diff main...HEAD --diff-filter=D --name-only | grep -E "\.test\." || true
 
 # Scope check
 git diff main...HEAD --name-only | wc -l
@@ -636,6 +636,20 @@ For multiple issues, run `/fullsolve` on each sequentially:
 
 Each issue gets its own worktree, PR, and quality validation.
 
+### Post-Batch: Merge Verification
+
+After processing a batch, run `sequant merge` to catch cross-issue integration gaps before merging:
+
+```bash
+/fullsolve 218
+/fullsolve 219
+/fullsolve 220
+sequant merge --check         # Verify no cross-issue conflicts
+/merger 218 219 220           # Merge all issues
+```
+
+`sequant merge --check` detects merge conflicts, template mirroring gaps, and file overlaps at zero AI cost. See `docs/reference/merge-command.md`.
+
 ---
 
 ## Output Verification

package/templates/skills/loop/SKILL.md

@@ -101,7 +101,7 @@ Extract:
 
 Find the worktree for this issue:
 ```bash
-git worktree list | grep -E "feature.*<issue-number>"
+git worktree list | grep -E "feature.*<issue-number>" || true
 ```
 
 Or check:

package/templates/skills/qa/SKILL.md

@@ -46,13 +46,13 @@ When invoked as `/qa`, your job is to:
 comments_json=$(gh issue view <issue-number> --json comments --jq '[.comments[].body]')
 exec_completed=$(echo "$comments_json" | \
   grep -o '{[^}]*}' | grep '"phase"' | \
-  jq -r 'select(.phase == "exec" and .status == "completed")' 2>/dev/null)
+  jq -r 'select(.phase == "exec" and .status == "completed")' 2>/dev/null || true)
 
 if [[ -z "$exec_completed" ]]; then
   # Check if any exec marker exists at all
   exec_any=$(echo "$comments_json" | \
     grep -o '{[^}]*}' | grep '"phase"' | \
-    jq -r 'select(.phase == "exec")' 2>/dev/null)
+    jq -r 'select(.phase == "exec")' 2>/dev/null || true)
 
   if [[ -n "$exec_any" ]]; then
     echo "⚠️ Exec phase not completed (status: $(echo "$exec_any" | jq -r '.status')). Run /exec first."
@@ -177,7 +177,7 @@ If no feature worktree exists (work was done directly on main):
 
 **Add RLS check if admin files modified:**
 ```bash
-admin_modified=$(git diff main...HEAD --name-only | grep -E "^app/admin/" | head -1)
+admin_modified=$(git diff main...HEAD --name-only | grep -E "^app/admin/" | head -1 || true)
 ```
 
 See [quality-gates.md](references/quality-gates.md) for detailed verdict synthesis.
@@ -306,10 +306,10 @@ See [quality-gates.md](references/quality-gates.md) for detailed verdict criteri
 
 ```bash
 # Type safety
-type_issues=$(git diff main...HEAD | grep -E ":\s*any[,)]|as any" | wc -l | xargs)
+type_issues=$(git diff main...HEAD | grep -E ":\s*any[,)]|as any" | wc -l | xargs || echo "0")
 
 # Deleted tests
-deleted_tests=$(git diff main...HEAD --diff-filter=D --name-only | grep -E "\\.test\\.|\\spec\\." | wc -l | xargs)
+deleted_tests=$(git diff main...HEAD --diff-filter=D --name-only | grep -E "\\.test\\.|\\spec\\." | wc -l | xargs || echo "0")
 
 # Scope check
 files_changed=$(git diff main...HEAD --name-only | wc -l | xargs)
@@ -355,7 +355,7 @@ If verdict is `READY_FOR_MERGE` or `AC_MET_BUT_NOT_A_PLUS`:
 
 **Detection:**
 ```bash
-scripts_changed=$(git diff main...HEAD --name-only | grep "^scripts/" | wc -l | xargs)
+scripts_changed=$(git diff main...HEAD --name-only | grep "^scripts/" | wc -l | xargs || echo "0")
 if [[ $scripts_changed -gt 0 ]]; then
   echo "Script changes detected. Run /verify before READY_FOR_MERGE"
 fi

package/templates/skills/solve/SKILL.md

@@ -100,10 +100,10 @@ When analyzing issues, check if `--base` flag should be recommended.
 
 ```bash
 # Check for feature branch references in issue body
-gh issue view <issue-number> --json body --jq '.body' | grep -iE "(feature/|branch from|based on|part of.*feature)"
+gh issue view <issue-number> --json body --jq '.body' | grep -iE "(feature/|branch from|based on|part of.*feature)" || true
 
 # Check issue labels for feature context
-gh issue view <issue-number> --json labels --jq '.labels[].name' | grep -iE "(dashboard|feature-|epic-)"
+gh issue view <issue-number> --json labels --jq '.labels[].name' | grep -iE "(dashboard|feature-|epic-)" || true
 
 # Check if project has defaultBase configured
 # Use the Read tool to check project settings
@@ -130,13 +130,13 @@ When analyzing multiple issues, determine if `--chain` flag should be recommende
 
 ```bash
 # Check for dependency keywords in issue body
-gh issue view <issue-number> --json body --jq '.body' | grep -iE "(depends on|blocked by|requires|after #|builds on)"
+gh issue view <issue-number> --json body --jq '.body' | grep -iE "(depends on|blocked by|requires|after #|builds on)" || true
 
 # Check for sequence labels
-gh issue view <issue-number> --json labels --jq '.labels[].name' | grep -iE "(part-[0-9]|step-[0-9]|phase-[0-9])"
+gh issue view <issue-number> --json labels --jq '.labels[].name' | grep -iE "(part-[0-9]|step-[0-9]|phase-[0-9])" || true
 
 # Check for related issue references
-gh issue view <issue-number> --json body --jq '.body' | grep -oE "#[0-9]+"
+gh issue view <issue-number> --json body --jq '.body' | grep -oE "#[0-9]+" || true
 ```
 
 **Recommend `--chain` when:**
@@ -201,7 +201,7 @@ Before generating output, check for in-flight work that may conflict:
 
 ```bash
 # List open worktrees
-git worktree list --porcelain 2>/dev/null | grep "^worktree" | cut -d' ' -f2
+git worktree list --porcelain 2>/dev/null | grep "^worktree" | cut -d' ' -f2 || true
 
 # For each worktree, get changed files
 git -C <worktree-path> diff --name-only main...HEAD 2>/dev/null
@@ -477,6 +477,28 @@ npx sequant run 152 --quality-loop --max-iterations 5
 npx sequant run 152 --dry-run
 ```
 
+### Post-Run: Merge Verification
+
+After batch execution, run merge checks before merging:
+
+```bash
+# Verify feature branches are safe to merge (auto-detects issues from last run)
+npx sequant merge --check
+
+# Full scan including residual pattern detection
+npx sequant merge --scan
+
+# Post results to each PR
+npx sequant merge --check --post
+```
+
+**Recommended workflow:**
+```bash
+npx sequant run 152 153 154        # implement
+npx sequant merge --check          # verify cross-issue integration
+/merger 152 153 154                # merge
+```
+
 ### Custom Base Branch
 
 The `--base` flag specifies which branch to create worktrees from:

package/templates/skills/spec/SKILL.md

@@ -37,7 +37,7 @@ When invoked as `/spec`, your job is to:
 ```bash
 # Check for existing phase markers
 phase_data=$(gh issue view <issue-number> --json comments --jq '[.comments[].body]' | \
-  grep -o '{[^}]*}' | grep '"phase"' | tail -1)
+  grep -o '{[^}]*}' | grep '"phase"' | tail -1 || true)
 
 if [[ -n "$phase_data" ]]; then
   phase=$(echo "$phase_data" | jq -r '.phase')
@@ -91,8 +91,8 @@ When called like `/spec <freeform description>`:
 ```bash
 # Extract AC from issue body and store in state
 npx tsx -e "
-import { extractAcceptanceCriteria } from './src/lib/ac-parser.js';
-import { StateManager } from './src/lib/workflow/state-manager.js';
+import { extractAcceptanceCriteria } from './src/lib/ac-parser.ts';
+import { StateManager } from './src/lib/workflow/state-manager.ts';
 
 const issueBody = \`<ISSUE_BODY_HERE>\`;
 const issueNumber = <ISSUE_NUMBER>;
@@ -103,13 +103,14 @@ console.log('Extracted AC:', JSON.stringify(ac, null, 2));
 
 if (ac.items.length > 0) {
   const manager = new StateManager();
-  // Initialize issue if not exists
-  const existing = await manager.getIssueState(issueNumber);
-  if (!existing) {
-    await manager.initializeIssue(issueNumber, issueTitle);
-  }
-  await manager.updateAcceptanceCriteria(issueNumber, ac);
-  console.log('AC stored in state for issue #' + issueNumber);
+  (async () => {
+    const existing = await manager.getIssueState(issueNumber);
+    if (!existing) {
+      await manager.initializeIssue(issueNumber, issueTitle);
+    }
+    await manager.updateAcceptanceCriteria(issueNumber, ac);
+    console.log('AC stored in state for issue #' + issueNumber);
+  })();
 }
 "
 ```
@@ -136,8 +137,8 @@ The parser supports multiple formats:
 ```bash
 # Lint AC for quality issues (skip if --skip-ac-lint flag is set)
 npx tsx -e "
-import { parseAcceptanceCriteria } from './src/lib/ac-parser.js';
-import { lintAcceptanceCriteria, formatACLintResults } from './src/lib/ac-linter.js';
+import { parseAcceptanceCriteria } from './src/lib/ac-parser.ts';
+import { lintAcceptanceCriteria, formatACLintResults } from './src/lib/ac-linter.ts';
 
 const issueBody = \`<ISSUE_BODY_HERE>\`;
 
@@ -230,12 +231,12 @@ Before creating the implementation plan, check if a custom base branch should be
 
 1. **Check for feature branch references in issue body**:
    ```bash
-   gh issue view <issue> --json body --jq '.body' | grep -iE "(feature/|branch from|based on|part of.*feature)"
+   gh issue view <issue> --json body --jq '.body' | grep -iE "(feature/|branch from|based on|part of.*feature)" || true
    ```
 
 2. **Check issue labels for feature context**:
    ```bash
-   gh issue view <issue> --json labels --jq '.labels[].name' | grep -iE "(dashboard|feature-|epic-)"
+   gh issue view <issue> --json labels --jq '.labels[].name' | grep -iE "(dashboard|feature-|epic-)" || true
    ```
 
 3. **Check if project has defaultBase configured**:
@@ -409,7 +410,7 @@ First, check if a `/solve` comment already exists for this issue:
 
 ```bash
 # Check issue comments for solve workflow
-gh issue view <issue-number> --json comments --jq '.comments[].body' | grep -l "## Solve Workflow for Issues:"
+gh issue view <issue-number> --json comments --jq '.comments[].body' | grep -l "## Solve Workflow for Issues:" || true
 ```
 
 **If solve comment found:**

package/templates/skills/testgen/SKILL.md

@@ -413,7 +413,7 @@ If an AC has verification method "N/A - Trivial", skip test generation and note
 If generating file-based tests (Unit Test, Integration Test), find the worktree:
 
 ```bash
-git worktree list | grep -E "feature.*<issue-number>"
+git worktree list | grep -E "feature.*<issue-number>" || true
 ```
 
 Or check: