sequant 1.16.0 → 1.17.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "sequant",
   "description": "Structured workflow system for Claude Code - GitHub issue resolution with spec, exec, test, and QA phases",
-  "version": "1.16.0",
+  "version": "1.16.1",
   "author": {
     "name": "sequant-io",
     "email": "hello@sequant.io"

package/README.md

@@ -4,6 +4,8 @@
 
 Solve GitHub issues with structured phases and quality gates — from issue to merge-ready PR.
 
+**[sequant.io](https://sequant.io)** — docs, guides, and getting started.
+
 [![npm version](https://img.shields.io/npm/v/sequant.svg)](https://www.npmjs.com/package/sequant)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
 
@@ -128,6 +130,7 @@ npx sequant run 123              # Single issue
 npx sequant run 1 2 3            # Batch (parallel)
 npx sequant run 123 --quality-loop
 npx sequant run 123 --base feature/dashboard  # Custom base branch
+npx sequant merge --check        # Verify batch before merging
 ```
 
 ---
@@ -155,6 +158,7 @@ npx sequant run 123 --base feature/dashboard  # Custom base branch
 
 | Command | Purpose |
 |---------|---------|
+| `/merger` | Multi-issue merge coordination |
 | `/testgen` | Generate test stubs from spec |
 | `/verify` | CLI/script execution verification |
 | `/setup` | Initialize Sequant in a project |
@@ -180,12 +184,13 @@ npx sequant update            # Update skill templates
 npx sequant doctor            # Check installation
 npx sequant status            # Show version and config
 npx sequant run <issues...>   # Execute workflow
+npx sequant merge <issues...> # Batch integration QA before merging
 npx sequant state <cmd>       # Manage workflow state (init/rebuild/clean)
 npx sequant stats             # View local workflow analytics
 npx sequant dashboard         # Launch real-time workflow dashboard
 ```
 
-See [Run Command Options](docs/reference/run-command.md), [State Command](docs/reference/state-command.md), and [Analytics](docs/reference/analytics.md) for details.
+See [Run Command Options](docs/reference/run-command.md), [Merge Command](docs/reference/merge-command.md), [State Command](docs/reference/state-command.md), and [Analytics](docs/reference/analytics.md) for details.
 
 ---
 

package/dist/bin/cli.js

@@ -122,7 +122,7 @@ program
     .description("Execute workflow for GitHub issues using Claude Agent SDK")
     .argument("[issues...]", "Issue numbers to process")
     .option("--phases <list>", "Phases to run (default: spec,exec,qa)")
-    .option("--sequential", "Run issues sequentially")
+    .option("--sequential", "Stop on first issue failure (default: continue)")
     .option("-d, --dry-run", "Preview without execution")
     .option("-v, --verbose", "Verbose output with streaming")
     .option("--timeout <seconds>", "Timeout per phase in seconds", parseInt)
@@ -145,6 +145,7 @@ program
     .option("--no-rebase", "Skip pre-PR rebase onto origin/main (use when you want to handle rebasing manually)")
     .option("--no-pr", "Skip PR creation after successful QA (manual PR workflow)")
     .option("-f, --force", "Force re-execution of completed issues (bypass pre-flight state guard)")
+    .option("--reflect", "Analyze run results and suggest improvements")
     .action(runCommand);
 program
     .command("merge")

package/dist/src/commands/run.d.ts

@@ -248,6 +248,12 @@ interface RunOptions {
      * 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;
 }
 /**
  * Execute a single phase for an issue using Claude Agent SDK

package/dist/src/commands/run.js

@@ -26,6 +26,7 @@ import { PhaseSpinner } from "../lib/phase-spinner.js";
 import { getGitDiffStats, getCommitHash, } from "../lib/workflow/git-diff-utils.js";
 import { getTokenUsageForRun } from "../lib/workflow/token-utils.js";
 import { reconcileStateAtStartup } from "../lib/workflow/state-utils.js";
+import { analyzeRun, formatReflection } from "../lib/workflow/run-reflect.js";
 /**
  * Slugify a title for branch naming
  */
@@ -1753,7 +1754,7 @@ export async function runCommand(issues, options) {
     else {
         console.log(chalk.gray(`  Phases: ${config.phases.join(" → ")}`));
     }
-    console.log(chalk.gray(`  Mode: ${config.sequential ? "sequential" : "parallel"}`));
+    console.log(chalk.gray(`  Mode: ${config.sequential ? "stop-on-failure" : "continue-on-failure"}`));
     if (config.qualityLoop) {
         console.log(chalk.gray(`  Quality loop: enabled (max ${config.maxIterations} iterations)`));
     }
@@ -1954,7 +1955,7 @@ export async function runCommand(issues, options) {
             }
         }
         else {
-            // Parallel execution (for now, just run sequentially but don't stop on failure)
+            // Default mode: run issues serially but continue on failure (don't stop)
             // TODO: Add proper parallel execution with listr2
             for (const issueNumber of issueNumbers) {
                 // Check if shutdown was triggered
@@ -2105,6 +2106,29 @@ export async function runCommand(issues, options) {
             console.log(colors.muted(`  📝 Log: ${logPath}`));
             console.log("");
         }
+        // Reflection analysis (--reflect flag)
+        if (mergedOptions.reflect && results.length > 0) {
+            const reflection = analyzeRun({
+                results,
+                issueInfoMap,
+                runLog: logWriter?.getRunLog() ?? null,
+                config: {
+                    phases: config.phases,
+                    qualityLoop: config.qualityLoop,
+                },
+            });
+            const reflectionOutput = formatReflection(reflection);
+            if (reflectionOutput) {
+                console.log(reflectionOutput);
+                console.log("");
+            }
+        }
+        // Suggest merge checks for multi-issue batches
+        if (results.length > 1 && passed > 0 && !config.dryRun) {
+            console.log(colors.muted("  💡 Verify batch integration before merging:"));
+            console.log(colors.muted("     sequant merge --check"));
+            console.log("");
+        }
         if (config.dryRun) {
             console.log(colors.warning("  ℹ️  This was a dry run. Use without --dry-run to execute."));
             console.log("");

package/dist/src/lib/upstream/assessment.js

@@ -234,9 +234,11 @@ export async function assessVersion(version, options = {}) {
     // Create assessment issue first (to get issue number for linking)
     const assessmentBody = generateAssessmentReport(assessment);
     const assessmentIssueNumber = await createAssessmentIssue(`Upstream: Claude Code ${release.tagName} Assessment`, assessmentBody, dryRun);
-    // Create issues for actionable findings
-    for (let i = 0; i < actionableFindings.length; i++) {
-        const updatedFinding = await createOrLinkFinding(actionableFindings[i], release.tagName, assessmentIssueNumber, dryRun);
+    // Create issues for actionable findings (excluding opportunities —
+    // opportunities are listed in the assessment but don't get individual issues)
+    const issueWorthy = actionableFindings.filter((f) => f.category !== "opportunity");
+    for (let i = 0; i < issueWorthy.length; i++) {
+        const updatedFinding = await createOrLinkFinding(issueWorthy[i], release.tagName, assessmentIssueNumber, dryRun);
         // Update in original findings array
         const originalIndex = findings.findIndex((f) => f.description === updatedFinding.description);
         if (originalIndex >= 0) {
@@ -370,6 +372,7 @@ function getDefaultBaseline() {
             Task: [".claude/skills/**/*.md"],
             MCP: [".claude/settings.json"],
         },
+        outOfScope: [],
     };
 }
 /**

package/dist/src/lib/upstream/relevance.d.ts

@@ -36,6 +36,11 @@ export declare function getImpactFiles(matchedKeywords: string[], dependencyMap:
  * Generate a title for a finding
  */
 export declare function generateTitle(category: FindingCategory, change: string): string;
+/**
+ * Check if a change matches any out-of-scope patterns from the baseline.
+ * Out-of-scope changes are skipped entirely during analysis.
+ */
+export declare function isOutOfScope(change: string, outOfScope?: string[]): boolean;
 /**
  * Analyze a single change against the baseline
  */

package/dist/src/lib/upstream/relevance.js

@@ -158,10 +158,34 @@ export function generateTitle(category, change) {
             return title;
     }
 }
+/**
+ * Check if a change matches any out-of-scope patterns from the baseline.
+ * Out-of-scope changes are skipped entirely during analysis.
+ */
+export function isOutOfScope(change, outOfScope = []) {
+    const changeLower = change.toLowerCase();
+    return outOfScope.some((pattern) => {
+        // Use the descriptive part before " - " as the match pattern
+        const matchPart = pattern.split(" - ")[0].toLowerCase();
+        return changeLower.includes(matchPart);
+    });
+}
 /**
  * Analyze a single change against the baseline
  */
 export function analyzeChange(change, baseline) {
+    // Skip out-of-scope changes early
+    if (isOutOfScope(change, baseline.outOfScope)) {
+        return {
+            category: "no-action",
+            title: change,
+            description: change,
+            impact: "none",
+            matchedKeywords: [],
+            matchedPatterns: [],
+            sequantFiles: [],
+        };
+    }
     // Match keywords and patterns
     const matchedKeywords = matchKeywords(change, baseline.keywords);
     const matchedPatterns = matchPatterns(change);

package/dist/src/lib/upstream/report.js

@@ -52,8 +52,9 @@ function getActionStatus(count, category) {
             return "Review needed";
         case "new-tool":
         case "hook-change":
-        case "opportunity":
             return "Issues created";
+        case "opportunity":
+            return "Noted for review";
         default:
             return "None";
     }
@@ -116,61 +117,32 @@ export function generateAssessmentReport(assessment) {
     lines.push(`| Opportunities | ${summary.opportunities} | ${getActionStatus(summary.opportunities, "opportunity")} |`);
     lines.push(`| No Action | ${summary.noAction} | None |`);
     lines.push("");
-    // Breaking Changes section
-    const breakingFindings = findings.filter((f) => f.category === "breaking");
-    lines.push("### Breaking Changes");
-    lines.push("");
-    if (breakingFindings.length === 0) {
-        lines.push("None detected.");
-    }
-    else {
-        breakingFindings.forEach((f, i) => {
-            lines.push(formatFinding(f, i));
-        });
-    }
-    lines.push("");
-    // Deprecations section
-    const deprecations = findings.filter((f) => f.category === "deprecation");
-    lines.push("### Deprecations");
-    lines.push("");
-    if (deprecations.length === 0) {
-        lines.push("None detected.");
-    }
-    else {
-        deprecations.forEach((f, i) => {
-            lines.push(formatFinding(f, i));
-        });
-    }
-    lines.push("");
-    // New Tools section
-    const newTools = findings.filter((f) => f.category === "new-tool");
-    lines.push("### New Tools");
+    // Actionable section — breaking changes, deprecations, new tools, hook changes
+    const actionableCategories = [
+        "breaking",
+        "deprecation",
+        "new-tool",
+        "hook-change",
+    ];
+    const actionableFindings = findings.filter((f) => actionableCategories.includes(f.category));
+    lines.push("### Actionable");
     lines.push("");
-    if (newTools.length === 0) {
-        lines.push("None detected.");
-    }
-    else {
-        newTools.forEach((f, i) => {
-            lines.push(formatFinding(f, i));
-        });
-    }
-    lines.push("");
-    // Hook Changes section
-    const hookChanges = findings.filter((f) => f.category === "hook-change");
-    lines.push("### Hook Changes");
+    lines.push("*Breaking changes, deprecations, and other items that affect sequant.*");
     lines.push("");
-    if (hookChanges.length === 0) {
+    if (actionableFindings.length === 0) {
         lines.push("None detected.");
     }
     else {
-        hookChanges.forEach((f, i) => {
+        actionableFindings.forEach((f, i) => {
             lines.push(formatFinding(f, i));
         });
     }
     lines.push("");
-    // Opportunities section
+    // Informational section — opportunities noted for human triage
     const opportunities = findings.filter((f) => f.category === "opportunity");
-    lines.push("### Feature Opportunities");
+    lines.push("### Informational");
+    lines.push("");
+    lines.push("*Opportunities noted for human triage. No individual issues auto-created.*");
     lines.push("");
     if (opportunities.length === 0) {
         lines.push("None detected.");

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

@@ -134,6 +134,8 @@ export interface Baseline {
     keywords: string[];
     /** Map of keywords to affected sequant files */
     dependencyMap: Record<string, string[]>;
+    /** Patterns for changes that are out of scope for sequant (skipped during analysis) */
+    outOfScope?: string[];
 }
 /**
  * Regex patterns for detecting change types

package/dist/src/lib/workflow/pr-status.d.ts

@@ -0,0 +1,47 @@
+/**
+ * PR merge detection and branch status utilities
+ *
+ * @module pr-status
+ * @example
+ * ```typescript
+ * import { checkPRMergeStatus, isBranchMergedIntoMain, isIssueMergedIntoMain } from './pr-status';
+ *
+ * // Check PR status via GitHub CLI
+ * const status = checkPRMergeStatus(123);
+ * if (status === 'MERGED') {
+ *   console.log('PR is merged');
+ * }
+ *
+ * // Check if branch is merged into main
+ * const isMerged = isBranchMergedIntoMain('feature/123-some-feature');
+ * ```
+ */
+/**
+ * PR merge status from GitHub
+ */
+export type PRMergeStatus = "MERGED" | "CLOSED" | "OPEN" | null;
+/**
+ * Check the merge status of a PR using the gh CLI
+ *
+ * @param prNumber - The PR number to check
+ * @returns "MERGED" | "CLOSED" | "OPEN" | null (null if PR not found or gh unavailable)
+ */
+export declare function checkPRMergeStatus(prNumber: number): PRMergeStatus;
+/**
+ * Check if a branch has been merged into main using git
+ *
+ * @param branchName - The branch name to check (e.g., "feature/33-some-title")
+ * @returns true if the branch is merged into main, false otherwise
+ */
+export declare function isBranchMergedIntoMain(branchName: string): boolean;
+/**
+ * Check if a feature branch for an issue is merged into main
+ *
+ * Tries multiple detection methods:
+ * 1. Check if branch exists and is merged via `git branch --merged main`
+ * 2. Check for merge commits mentioning the issue
+ *
+ * @param issueNumber - The issue number to check
+ * @returns true if the issue's work is merged into main
+ */
+export declare function isIssueMergedIntoMain(issueNumber: number): boolean;

package/dist/src/lib/workflow/pr-status.js

@@ -0,0 +1,129 @@
+/**
+ * PR merge detection and branch status utilities
+ *
+ * @module pr-status
+ * @example
+ * ```typescript
+ * import { checkPRMergeStatus, isBranchMergedIntoMain, isIssueMergedIntoMain } from './pr-status';
+ *
+ * // Check PR status via GitHub CLI
+ * const status = checkPRMergeStatus(123);
+ * if (status === 'MERGED') {
+ *   console.log('PR is merged');
+ * }
+ *
+ * // Check if branch is merged into main
+ * const isMerged = isBranchMergedIntoMain('feature/123-some-feature');
+ * ```
+ */
+import { spawnSync } from "child_process";
+/**
+ * Check the merge status of a PR using the gh CLI
+ *
+ * @param prNumber - The PR number to check
+ * @returns "MERGED" | "CLOSED" | "OPEN" | null (null if PR not found or gh unavailable)
+ */
+export function checkPRMergeStatus(prNumber) {
+    try {
+        const result = spawnSync("gh", ["pr", "view", String(prNumber), "--json", "state", "-q", ".state"], { stdio: "pipe", timeout: 10000 });
+        if (result.status === 0 && result.stdout) {
+            const state = result.stdout.toString().trim().toUpperCase();
+            if (state === "MERGED")
+                return "MERGED";
+            if (state === "CLOSED")
+                return "CLOSED";
+            if (state === "OPEN")
+                return "OPEN";
+        }
+    }
+    catch {
+        // gh not available or error - return null
+    }
+    return null;
+}
+/**
+ * Check if a branch has been merged into main using git
+ *
+ * @param branchName - The branch name to check (e.g., "feature/33-some-title")
+ * @returns true if the branch is merged into main, false otherwise
+ */
+export function isBranchMergedIntoMain(branchName) {
+    try {
+        // Get branches merged into main
+        const result = spawnSync("git", ["branch", "--merged", "main"], {
+            stdio: "pipe",
+            timeout: 10000,
+        });
+        if (result.status === 0 && result.stdout) {
+            const mergedBranches = result.stdout.toString();
+            // Check if our branch is in the list (handle both local and remote refs)
+            return (mergedBranches.includes(branchName) ||
+                mergedBranches.includes(`remotes/origin/${branchName}`));
+        }
+    }
+    catch {
+        // git command failed - return false
+    }
+    return false;
+}
+/**
+ * Check if a feature branch for an issue is merged into main
+ *
+ * Tries multiple detection methods:
+ * 1. Check if branch exists and is merged via `git branch --merged main`
+ * 2. Check for merge commits mentioning the issue
+ *
+ * @param issueNumber - The issue number to check
+ * @returns true if the issue's work is merged into main
+ */
+export function isIssueMergedIntoMain(issueNumber) {
+    try {
+        // Method 1: Check if any feature branch for this issue is merged
+        const listResult = spawnSync("git", ["branch", "-a"], {
+            stdio: "pipe",
+            timeout: 10000,
+        });
+        if (listResult.status === 0 && listResult.stdout) {
+            const branches = listResult.stdout.toString();
+            // Find branches matching feature/<issue>-*
+            const branchPattern = new RegExp(`feature/${issueNumber}-[^\\s]+`, "g");
+            const matchedBranches = branches.match(branchPattern);
+            if (matchedBranches) {
+                for (const branch of matchedBranches) {
+                    const cleanBranch = branch.replace(/^\*?\s*/, "").trim();
+                    if (isBranchMergedIntoMain(cleanBranch)) {
+                        return true;
+                    }
+                }
+            }
+        }
+        // Method 2: Check for merge commits mentioning the issue
+        // Use specific merge patterns to avoid false positives from
+        // unrelated commits that merely reference the issue number
+        const logResult = spawnSync("git", [
+            "log",
+            "main",
+            "--oneline",
+            "-20",
+            "--grep",
+            `Merge #${issueNumber}`,
+            "--grep",
+            `Merge.*#${issueNumber}`,
+            "--grep",
+            `(#${issueNumber})`,
+        ], {
+            stdio: "pipe",
+            timeout: 10000,
+        });
+        if (logResult.status === 0 && logResult.stdout) {
+            const commits = logResult.stdout.toString().trim();
+            if (commits.length > 0) {
+                return true;
+            }
+        }
+    }
+    catch {
+        // git command failed - return false
+    }
+    return false;
+}

package/dist/src/lib/workflow/run-reflect.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Run reflection analysis — analyzes completed run data and suggests improvements.
+ *
+ * Used by the `--reflect` flag on `sequant run` to provide post-run insights.
+ */
+import type { IssueResult } from "./types.js";
+import type { RunLog } from "./run-log-schema.js";
+export interface ReflectionInput {
+    results: IssueResult[];
+    issueInfoMap: Map<number, {
+        title: string;
+        labels: string[];
+    }>;
+    runLog: Omit<RunLog, "endTime"> | null;
+    config: {
+        phases: string[];
+        qualityLoop: boolean;
+    };
+}
+export interface ReflectionOutput {
+    observations: string[];
+    suggestions: string[];
+}
+/**
+ * Analyze a completed run and return observations + suggestions.
+ */
+export declare function analyzeRun(input: ReflectionInput): ReflectionOutput;
+/**
+ * Format reflection output as a box with observations and suggestions.
+ * Enforces max 10 content lines.
+ */
+export declare function formatReflection(output: ReflectionOutput): string;