sequant 1.15.4 → 1.16.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.15.4",
+  "version": "1.16.0",
   "author": {
     "name": "sequant-io",
     "email": "hello@sequant.io"

package/dist/bin/cli.js

@@ -44,6 +44,7 @@ import { statsCommand } from "../src/commands/stats.js";
 import { dashboardCommand } from "../src/commands/dashboard.js";
 import { stateInitCommand, stateRebuildCommand, stateCleanCommand, } from "../src/commands/state.js";
 import { syncCommand, areSkillsOutdated } from "../src/commands/sync.js";
+import { mergeCommand } from "../src/commands/merge.js";
 import { getManifest } from "../src/lib/manifest.js";
 const program = new Command();
 // Handle --no-color before parsing
@@ -145,6 +146,18 @@ program
     .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)")
     .action(runCommand);
+program
+    .command("merge")
+    .description("Batch-level integration QA — verify feature branches before merging")
+    .argument("[issues...]", "Issue numbers to check (auto-detects from most recent run if omitted)")
+    .option("--check", "Run Phase 1 deterministic checks (default)")
+    .option("--scan", "Run Phase 1 + Phase 2 residual pattern detection")
+    .option("--review", "Run Phase 1 + 2 + 3 AI briefing")
+    .option("--all", "Run all phases")
+    .option("--post", "Post report to GitHub as PR comments")
+    .option("--json", "Output as JSON")
+    .option("-v, --verbose", "Enable verbose output")
+    .action(mergeCommand);
 program
     .command("logs")
     .description("View and analyze workflow run logs")

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

@@ -0,0 +1,22 @@
+/**
+ * sequant merge - Batch-level integration QA for completed runs
+ *
+ * Runs deterministic checks on feature branches from a `sequant run` batch
+ * to catch integration issues before human review.
+ *
+ * Phases:
+ * - --check (Phase 1): Combined branch test, mirroring, overlap detection
+ * - --scan  (Phase 1+2): Adds residual pattern detection
+ * - --review (Phase 1+2+3): Adds AI briefing (stub)
+ * - --all: Runs all phases
+ * - --post: Post report to GitHub PRs
+ */
+import type { MergeCommandOptions } from "../lib/merge-check/types.js";
+/**
+ * Determine exit code from batch verdict
+ */
+export declare function getExitCode(batchVerdict: string): number;
+/**
+ * Main merge command handler
+ */
+export declare function mergeCommand(issues: string[], options: MergeCommandOptions): Promise<void>;

package/dist/src/commands/merge.js

@@ -0,0 +1,109 @@
+/**
+ * sequant merge - Batch-level integration QA for completed runs
+ *
+ * Runs deterministic checks on feature branches from a `sequant run` batch
+ * to catch integration issues before human review.
+ *
+ * Phases:
+ * - --check (Phase 1): Combined branch test, mirroring, overlap detection
+ * - --scan  (Phase 1+2): Adds residual pattern detection
+ * - --review (Phase 1+2+3): Adds AI briefing (stub)
+ * - --all: Runs all phases
+ * - --post: Post report to GitHub PRs
+ */
+import { spawnSync } from "child_process";
+import { ui, colors } from "../lib/cli-ui.js";
+import { runMergeChecks, formatReportMarkdown, } from "../lib/merge-check/index.js";
+/**
+ * Determine exit code from batch verdict
+ */
+export function getExitCode(batchVerdict) {
+    switch (batchVerdict) {
+        case "READY":
+            return 0;
+        case "NEEDS_ATTENTION":
+            return 1;
+        case "BLOCKED":
+            return 2;
+        default:
+            return 1;
+    }
+}
+/**
+ * Get the git repository root
+ */
+function getRepoRoot() {
+    const result = spawnSync("git", ["rev-parse", "--show-toplevel"], {
+        stdio: "pipe",
+        encoding: "utf-8",
+    });
+    if (result.status !== 0) {
+        throw new Error("Not in a git repository");
+    }
+    return result.stdout.trim();
+}
+/**
+ * Main merge command handler
+ */
+export async function mergeCommand(issues, options) {
+    // Default to --check if no phase flag is specified
+    if (!options.check && !options.scan && !options.review && !options.all) {
+        options.check = true;
+    }
+    const repoRoot = getRepoRoot();
+    const issueNumbers = issues
+        .map((i) => parseInt(i, 10))
+        .filter((n) => !isNaN(n));
+    // Determine mode label
+    let mode = "check";
+    if (options.all)
+        mode = "all";
+    else if (options.review)
+        mode = "review";
+    else if (options.scan)
+        mode = "scan";
+    if (!options.json) {
+        console.log(ui.headerBox("SEQUANT MERGE"));
+        console.log("");
+        console.log(colors.muted(issueNumbers.length > 0
+            ? `Checking issues: ${issueNumbers.map((i) => `#${i}`).join(", ")} (mode: ${mode})`
+            : `Auto-detecting issues from most recent run (mode: ${mode})`));
+        console.log("");
+    }
+    try {
+        const report = await runMergeChecks(issueNumbers, options, repoRoot);
+        if (options.json) {
+            // JSON output: serialize the report (convert Map to object)
+            const jsonReport = {
+                ...report,
+                issueVerdicts: Object.fromEntries(report.issueVerdicts),
+            };
+            console.log(JSON.stringify(jsonReport, null, 2));
+        }
+        else {
+            // Markdown output
+            const markdown = formatReportMarkdown(report);
+            console.log(markdown);
+            // Phase 3 stub
+            if (options.review || options.all) {
+                console.log("");
+                console.log(colors.muted("Phase 3 (AI briefing) is not yet implemented. Use --check or --scan for deterministic checks."));
+            }
+        }
+        // Set exit code based on verdict
+        const exitCode = getExitCode(report.batchVerdict);
+        if (exitCode !== 0) {
+            process.exitCode = exitCode;
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (options.json) {
+            console.log(JSON.stringify({ error: message }, null, 2));
+        }
+        else {
+            console.error(ui.errorBox("Merge Check Failed", message));
+        }
+        process.exitCode = 2;
+    }
+}

package/dist/src/lib/merge-check/combined-branch-test.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Combined branch testing (AC-1)
+ *
+ * Creates a temporary branch merging all feature branches from a run batch,
+ * runs npm test && npm run build on the combined state, and reports results.
+ */
+import type { BranchInfo, CheckResult, BranchCheckResult, CheckFinding } from "./types.js";
+/**
+ * Create temp branch, merge all feature branches, run tests and build.
+ *
+ * @param branches - Feature branches to merge
+ * @param repoRoot - Path to the git repository root
+ * @returns CheckResult with combined test findings
+ */
+export declare function runCombinedBranchTest(branches: BranchInfo[], repoRoot: string): CheckResult;
+export declare function buildResult(branchResults: BranchCheckResult[], batchFindings: CheckFinding[], startTime: number): CheckResult;

package/dist/src/lib/merge-check/combined-branch-test.js

@@ -0,0 +1,179 @@
+/**
+ * Combined branch testing (AC-1)
+ *
+ * Creates a temporary branch merging all feature branches from a run batch,
+ * runs npm test && npm run build on the combined state, and reports results.
+ */
+import { spawnSync } from "child_process";
+import { getBranchRef } from "./types.js";
+/**
+ * Run a git command and return the result
+ */
+function git(args, cwd) {
+    const result = spawnSync("git", args, {
+        cwd,
+        stdio: "pipe",
+        encoding: "utf-8",
+    });
+    return {
+        ok: result.status === 0,
+        stdout: result.stdout?.trim() ?? "",
+        stderr: result.stderr?.trim() ?? "",
+    };
+}
+/**
+ * Run npm command and return result
+ */
+function npm(args, cwd) {
+    const result = spawnSync("npm", args, {
+        cwd,
+        stdio: "pipe",
+        encoding: "utf-8",
+        timeout: 120_000, // 2 min timeout for test/build
+    });
+    return {
+        ok: result.status === 0,
+        stdout: result.stdout?.trim() ?? "",
+        stderr: result.stderr?.trim() ?? "",
+    };
+}
+/**
+ * Create temp branch, merge all feature branches, run tests and build.
+ *
+ * @param branches - Feature branches to merge
+ * @param repoRoot - Path to the git repository root
+ * @returns CheckResult with combined test findings
+ */
+export function runCombinedBranchTest(branches, repoRoot) {
+    const startTime = Date.now();
+    const tempBranch = `merge-check/temp-${Date.now()}`;
+    const branchResults = [];
+    const batchFindings = [];
+    const mergeAttempts = [];
+    // Save current branch to restore in finally block
+    const originalBranch = git(["rev-parse", "--abbrev-ref", "HEAD"], repoRoot);
+    try {
+        // Fetch latest from remote
+        git(["fetch", "origin"], repoRoot);
+        // Create temp branch from main
+        const createResult = git(["checkout", "-b", tempBranch, "origin/main"], repoRoot);
+        if (!createResult.ok) {
+            batchFindings.push({
+                check: "combined-branch-test",
+                severity: "error",
+                message: `Failed to create temp branch: ${createResult.stderr}`,
+            });
+            return buildResult(branchResults, batchFindings, startTime);
+        }
+        // Merge each feature branch
+        for (const branch of branches) {
+            const mergeResult = git(["merge", "--no-ff", "--no-edit", getBranchRef(branch)], repoRoot);
+            if (mergeResult.ok) {
+                mergeAttempts.push({
+                    issueNumber: branch.issueNumber,
+                    branch: branch.branch,
+                    success: true,
+                });
+                branchResults.push({
+                    issueNumber: branch.issueNumber,
+                    verdict: "PASS",
+                    findings: [
+                        {
+                            check: "combined-branch-test",
+                            severity: "info",
+                            message: `Branch merged cleanly into combined state`,
+                            issueNumber: branch.issueNumber,
+                        },
+                    ],
+                });
+            }
+            else {
+                // Get conflicting files
+                const conflictResult = git(["diff", "--name-only", "--diff-filter=U"], repoRoot);
+                const conflictFiles = conflictResult.stdout
+                    ? conflictResult.stdout.split("\n")
+                    : [];
+                mergeAttempts.push({
+                    issueNumber: branch.issueNumber,
+                    branch: branch.branch,
+                    success: false,
+                    conflictFiles,
+                    error: mergeResult.stderr,
+                });
+                branchResults.push({
+                    issueNumber: branch.issueNumber,
+                    verdict: "FAIL",
+                    findings: [
+                        {
+                            check: "combined-branch-test",
+                            severity: "error",
+                            message: `Merge conflict with ${conflictFiles.length} file(s): ${conflictFiles.join(", ")}`,
+                            issueNumber: branch.issueNumber,
+                        },
+                    ],
+                });
+                // Abort the failed merge and continue
+                git(["merge", "--abort"], repoRoot);
+            }
+        }
+        // If any merges failed, skip tests but report what we have
+        const failedMerges = mergeAttempts.filter((m) => !m.success);
+        if (failedMerges.length > 0) {
+            batchFindings.push({
+                check: "combined-branch-test",
+                severity: "error",
+                message: `${failedMerges.length}/${branches.length} branches had merge conflicts — skipping test/build`,
+            });
+            return buildResult(branchResults, batchFindings, startTime);
+        }
+        // Run npm test
+        const testResult = npm(["test"], repoRoot);
+        if (testResult.ok) {
+            batchFindings.push({
+                check: "combined-branch-test",
+                severity: "info",
+                message: "npm test passed on combined state",
+            });
+        }
+        else {
+            batchFindings.push({
+                check: "combined-branch-test",
+                severity: "error",
+                message: `npm test failed on combined state: ${testResult.stderr.slice(0, 500)}`,
+            });
+        }
+        // Run npm run build
+        const buildResult2 = npm(["run", "build"], repoRoot);
+        if (buildResult2.ok) {
+            batchFindings.push({
+                check: "combined-branch-test",
+                severity: "info",
+                message: "npm run build passed on combined state",
+            });
+        }
+        else {
+            batchFindings.push({
+                check: "combined-branch-test",
+                severity: "error",
+                message: `npm run build failed on combined state: ${buildResult2.stderr.slice(0, 500)}`,
+            });
+        }
+        return buildResult(branchResults, batchFindings, startTime);
+    }
+    finally {
+        // Clean up: restore original branch and delete temp branch
+        const restoreBranch = originalBranch.ok ? originalBranch.stdout : "main";
+        git(["checkout", restoreBranch], repoRoot);
+        git(["branch", "-D", tempBranch], repoRoot);
+    }
+}
+export function buildResult(branchResults, batchFindings, startTime) {
+    const hasErrors = batchFindings.some((f) => f.severity === "error");
+    return {
+        name: "combined-branch-test",
+        passed: !hasErrors,
+        branchResults,
+        batchFindings,
+        durationMs: Date.now() - startTime,
+    };
+}

package/dist/src/lib/merge-check/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Merge check orchestrator
+ *
+ * Coordinates all merge-check modules and resolves branches
+ * from run logs and git state.
+ */
+import { type RunLog } from "../workflow/run-log-schema.js";
+import type { BranchInfo, CheckResult, MergeCommandOptions, MergeReport } from "./types.js";
+import { formatReportMarkdown, formatBranchReportMarkdown, postReportToGitHub } from "./report.js";
+/**
+ * Find the most recent run log file
+ */
+export declare function findMostRecentLog(logDir: string): RunLog | null;
+/**
+ * Resolve branches from issue numbers.
+ *
+ * Uses git worktree list and remote branch patterns to find
+ * the feature branches for each issue.
+ */
+export declare function resolveBranches(issueNumbers: number[], repoRoot: string, runLog?: RunLog | null): BranchInfo[];
+/**
+ * Determine which checks to run based on command options.
+ *
+ * --scan, --review, and --all currently return the same checks because
+ * Phase 3 (AI briefing) is not yet implemented. When Phase 3 is added,
+ * --review and --all will include additional AI-powered checks.
+ * The distinction is preserved so callers can detect review mode
+ * and show the Phase 3 stub message (see merge.ts).
+ */
+export declare function getChecksToRun(options: MergeCommandOptions): string[];
+/**
+ * Run all merge checks and produce a report.
+ *
+ * @param issueNumbers - Issue numbers to check (empty = auto-detect from most recent run)
+ * @param options - Command options controlling which checks to run
+ * @param repoRoot - Path to the git repository root
+ * @returns MergeReport with all findings
+ */
+export declare function runMergeChecks(issueNumbers: number[], options: MergeCommandOptions, repoRoot: string): Promise<MergeReport>;
+export type { MergeReport, MergeCommandOptions, BranchInfo, CheckResult };
+export { formatReportMarkdown, formatBranchReportMarkdown, postReportToGitHub };

package/dist/src/lib/merge-check/index.js

@@ -0,0 +1,225 @@
+/**
+ * Merge check orchestrator
+ *
+ * Coordinates all merge-check modules and resolves branches
+ * from run logs and git state.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+import { spawnSync } from "child_process";
+import { RunLogSchema, LOG_PATHS, } from "../workflow/run-log-schema.js";
+import { getGitDiffStats } from "../workflow/git-diff-utils.js";
+import { DEFAULT_MIRROR_PAIRS } from "./types.js";
+import { runCombinedBranchTest } from "./combined-branch-test.js";
+import { runMirroringCheck } from "./mirroring-check.js";
+import { runOverlapDetection } from "./overlap-detection.js";
+import { runResidualPatternScan } from "./residual-pattern-scan.js";
+import { buildReport, formatReportMarkdown, formatBranchReportMarkdown, postReportToGitHub, } from "./report.js";
+/**
+ * Resolve log directory path
+ */
+function resolveLogDir(customPath) {
+    if (customPath) {
+        return customPath.replace("~", os.homedir());
+    }
+    const projectPath = LOG_PATHS.project;
+    if (fs.existsSync(projectPath)) {
+        return projectPath;
+    }
+    const userPath = LOG_PATHS.user.replace("~", os.homedir());
+    if (fs.existsSync(userPath)) {
+        return userPath;
+    }
+    return projectPath;
+}
+/**
+ * Find the most recent run log file
+ */
+export function findMostRecentLog(logDir) {
+    if (!fs.existsSync(logDir)) {
+        return null;
+    }
+    const files = fs
+        .readdirSync(logDir)
+        .filter((f) => f.startsWith("run-") && f.endsWith(".json"))
+        .sort()
+        .reverse();
+    if (files.length === 0) {
+        return null;
+    }
+    const content = fs.readFileSync(path.join(logDir, files[0]), "utf-8");
+    const parsed = RunLogSchema.safeParse(JSON.parse(content));
+    if (!parsed.success) {
+        return null;
+    }
+    return parsed.data;
+}
+/**
+ * Resolve branches from issue numbers.
+ *
+ * Uses git worktree list and remote branch patterns to find
+ * the feature branches for each issue.
+ */
+export function resolveBranches(issueNumbers, repoRoot, runLog) {
+    const branches = [];
+    // Get remote branches matching feature pattern
+    const branchResult = spawnSync("git", ["-C", repoRoot, "branch", "-r", "--list", "origin/feature/*"], { stdio: "pipe", encoding: "utf-8" });
+    const remoteBranches = branchResult.stdout
+        ? branchResult.stdout
+            .split("\n")
+            .map((b) => b.trim().replace("origin/", ""))
+            .filter(Boolean)
+        : [];
+    // Also check worktrees for local-only branches
+    const worktreeResult = spawnSync("git", ["-C", repoRoot, "worktree", "list", "--porcelain"], { stdio: "pipe", encoding: "utf-8" });
+    const worktreePaths = new Map();
+    let currentPath = "";
+    for (const line of (worktreeResult.stdout ?? "").split("\n")) {
+        if (line.startsWith("worktree ")) {
+            currentPath = line.slice(9);
+        }
+        else if (line.startsWith("branch refs/heads/")) {
+            const branch = line.slice(18);
+            worktreePaths.set(branch, currentPath);
+        }
+    }
+    // Get run log issue info for titles
+    const issueInfo = new Map();
+    if (runLog) {
+        for (const issue of runLog.issues) {
+            issueInfo.set(issue.issueNumber, {
+                title: issue.title,
+                prNumber: issue.prNumber,
+            });
+        }
+    }
+    for (const issueNumber of issueNumbers) {
+        // Find the branch for this issue
+        const branchPattern = new RegExp(`^feature/${issueNumber}-`);
+        const branch = remoteBranches.find((b) => branchPattern.test(b)) ??
+            Array.from(worktreePaths.keys()).find((b) => branchPattern.test(b));
+        if (!branch) {
+            console.error(`No branch found for issue #${issueNumber}`);
+            continue;
+        }
+        // Get modified files from the branch
+        const worktreePath = worktreePaths.get(branch);
+        let filesModified = [];
+        if (worktreePath) {
+            // Use worktree for diff
+            const diffStats = getGitDiffStats(worktreePath);
+            filesModified = diffStats.filesModified;
+        }
+        else {
+            // Use remote branch diff
+            const diffResult = spawnSync("git", [
+                "-C",
+                repoRoot,
+                "diff",
+                "--name-only",
+                `origin/main...origin/${branch}`,
+            ], { stdio: "pipe", encoding: "utf-8" });
+            filesModified = diffResult.stdout
+                ? diffResult.stdout.split("\n").filter(Boolean)
+                : [];
+        }
+        const info = issueInfo.get(issueNumber);
+        const title = info?.title ?? fetchIssueTitle(issueNumber) ?? `Issue #${issueNumber}`;
+        branches.push({
+            issueNumber,
+            title,
+            branch,
+            worktreePath,
+            prNumber: info?.prNumber,
+            filesModified,
+        });
+    }
+    return branches;
+}
+/**
+ * Fetch issue title from GitHub via gh CLI.
+ * Returns null if gh is not available or the issue doesn't exist.
+ */
+function fetchIssueTitle(issueNumber) {
+    const result = spawnSync("gh", ["issue", "view", String(issueNumber), "--json", "title", "--jq", ".title"], { stdio: "pipe", encoding: "utf-8", timeout: 10_000 });
+    if (result.status !== 0 || !result.stdout?.trim()) {
+        return null;
+    }
+    return result.stdout.trim();
+}
+/**
+ * Determine which checks to run based on command options.
+ *
+ * --scan, --review, and --all currently return the same checks because
+ * Phase 3 (AI briefing) is not yet implemented. When Phase 3 is added,
+ * --review and --all will include additional AI-powered checks.
+ * The distinction is preserved so callers can detect review mode
+ * and show the Phase 3 stub message (see merge.ts).
+ */
+export function getChecksToRun(options) {
+    const phase1 = ["combined-branch-test", "mirroring", "overlap-detection"];
+    const phase2 = ["residual-pattern-scan"];
+    // Phase 3 checks will be added here when AI briefing is implemented
+    // const phase3 = ["ai-briefing"];
+    if (options.all || options.review || options.scan) {
+        return [...phase1, ...phase2];
+    }
+    // Default --check: Phase 1 only
+    return phase1;
+}
+/**
+ * Run all merge checks and produce a report.
+ *
+ * @param issueNumbers - Issue numbers to check (empty = auto-detect from most recent run)
+ * @param options - Command options controlling which checks to run
+ * @param repoRoot - Path to the git repository root
+ * @returns MergeReport with all findings
+ */
+export async function runMergeChecks(issueNumbers, options, repoRoot) {
+    const logDir = resolveLogDir();
+    let runLog = null;
+    // Auto-detect issues from most recent run log if none specified
+    if (issueNumbers.length === 0) {
+        runLog = findMostRecentLog(logDir);
+        if (!runLog) {
+            throw new Error("No run logs found. Specify issue numbers or run `sequant run` first.");
+        }
+        issueNumbers = runLog.issues.map((i) => i.issueNumber);
+    }
+    else {
+        // Still try to load run log for metadata
+        runLog = findMostRecentLog(logDir);
+    }
+    // Resolve branches for each issue
+    const branches = resolveBranches(issueNumbers, repoRoot, runLog);
+    if (branches.length === 0) {
+        throw new Error("No feature branches found for the specified issues. " +
+            "Ensure branches exist (pushed to remote or in local worktrees).");
+    }
+    // Determine which checks to run
+    const checksToRun = getChecksToRun(options);
+    const checkResults = [];
+    // Phase 1: Deterministic checks
+    if (checksToRun.includes("combined-branch-test")) {
+        checkResults.push(runCombinedBranchTest(branches, repoRoot));
+    }
+    if (checksToRun.includes("mirroring")) {
+        checkResults.push(runMirroringCheck(branches, DEFAULT_MIRROR_PAIRS));
+    }
+    if (checksToRun.includes("overlap-detection")) {
+        checkResults.push(runOverlapDetection(branches, repoRoot));
+    }
+    // Phase 2: Residual pattern detection
+    if (checksToRun.includes("residual-pattern-scan")) {
+        checkResults.push(runResidualPatternScan(branches, repoRoot));
+    }
+    // Build report
+    const report = buildReport(branches, checkResults, runLog?.runId);
+    // Post to GitHub if requested
+    if (options.post) {
+        postReportToGitHub(report);
+    }
+    return report;
+}
+export { formatReportMarkdown, formatBranchReportMarkdown, postReportToGitHub };

package/dist/src/lib/merge-check/mirroring-check.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Template/source mirroring check (AC-2)
+ *
+ * Detects paired directories and verifies that when a file is modified
+ * in one location, the corresponding file in the mirror is also modified.
+ */
+import type { BranchInfo, CheckResult, MirrorPair } from "./types.js";
+/**
+ * Run mirroring check across all branches
+ *
+ * For each file modified by a branch, if it falls within a mirrored directory,
+ * verify that the corresponding mirror file was also modified.
+ */
+export declare function runMirroringCheck(branches: BranchInfo[], mirrorPairs: MirrorPair[]): CheckResult;