Merge Command

Quick Start: Run batch-level integration checks on feature branches after sequant run completes. Catches cross-issue gaps that per-issue QA misses — merge conflicts, template mirroring gaps, residual patterns, and file overlaps — at zero AI cost.

Access

Command: npx sequant merge [issues...] [options]
Requirements:
- Feature branches exist (pushed to remote or in local worktrees)
- GitHub CLI authenticated (gh auth login) for --post flag
Relationship: Runs AFTER sequant run, BEFORE /merger

sequant run 265 298 299 300   # implement
sequant merge --check         # verify (this command)
/merger 265 298 299 300       # merge

Usage

Check a Completed Batch

npx sequant merge 265 298 299 300 --check

Runs Phase 1 deterministic checks: combined branch test, template mirroring, file overlap detection, and external PR overlap.

Auto-Detect Issues from Last Run

npx sequant merge --check

Reads the most recent run log from .sequant/logs/ and auto-detects which issues to check.

Full Scan with Residual Pattern Detection

npx sequant merge 265 298 299 300 --scan

Runs Phase 1 + Phase 2: adds residual pattern detection that finds instances of removed code patterns still present elsewhere in the codebase.

Post Results to GitHub

npx sequant merge 265 298 299 300 --check --post

Posts per-issue merge readiness reports as comments on each PR.

Wait for CI, Then Verify (`--watch`)

npx sequant merge 818 --watch

--watch kills the “merge after green” polling loop: instead of running merge-check against checks that are still in flight, it polls each resolved PR’s CI rollup until every check reaches a terminal state, then runs the normal merge-check phases and prints the usual report. When the command exits, the verdict is real.

Key properties:

It never merges. --watch only decides when the existing report runs — the human merge gate is unchanged.
Foreground only. A plain in-process poll loop — no daemon, no background process, no OS notifications. Chain on the exit code if you want a notification (sequant merge 818 --watch && notify-send ready).
Composes with the depth flags and --post — e.g. sequant merge 818 --watch --scan --post waits for CI, then runs the Phase 1+2 checks and posts the report.
Dispatch blocks short-circuit to BLOCKED instead of polling until timeout: a CONFLICTING mergeable state (merge conflicts block CI dispatch), zero checks after a dispatch-blocking condition, and a uniformly-failing board whose check-run annotations show the runner was never started (GitHub Actions billing/spending-limit lockout) are each detected and reported with the cause.

Uses GitHubProvider with statusCheckRollup (the --json checks field is known-broken).

Options & Settings

Option	Description	Default
`--check`	Run Phase 1 deterministic checks	Default if no flag specified
`--scan`	Run Phase 1 + Phase 2 residual pattern detection	-
`--review`	Run Phase 1 + 2 + 3 AI briefing (stub)	-
`--all`	Run all phases	-
`--post`	Post report to GitHub as PR comments	-
`--watch`	Wait for each PR’s CI checks to reach a terminal state before running merge-check (never merges)	-
`--interval <seconds>`	Watch poll interval (whole seconds, minimum `1`)	`30`
`--timeout <seconds>`	Watch give-up timeout (whole seconds, minimum `1`)	`1800` (30 min)
`--json`	Output as JSON (for scripting)	-
`-v, --verbose`	Enable verbose output	-

--interval and --timeout accept whole seconds only. A value that is not a positive integer is rejected with an error rather than silently coerced — note that --timeout 30m is not 30 minutes and is refused, so write --timeout 1800.

Exit Codes

Code	Meaning
`0`	All checks pass (READY)
`1`	Warnings found (NEEDS_ATTENTION)
`2`	Failures found, or a dispatch block detected under `--watch` (BLOCKED)
`3`	`--watch` timed out before CI reached a terminal state

Checks Performed

Phase 1: Deterministic Checks (`--check`)

Check	What It Does	Verdict
Combined Branch Test	Creates temp branch, merges all feature branches, reinstalls dependencies if the merge moved a lockfile, then runs the detected package manager’s `test` and `build` scripts	FAIL if merge conflict, dependency install failure, or test/build failure
Template Mirroring	Verifies `.claude/skills/` changes have matching `templates/skills/` updates (and vice versa for `hooks/`)	WARN if unmirrored changes found
File Overlap Detection	Flags files modified by multiple issues in the batch, classifies as additive vs conflicting	WARN if overlaps found
External PR Overlap	Lists open PRs on origin that are not in the batch but change files the batch changes. One warning per PR names the PR number, head branch and shared paths. PRs whose head branch is in the batch are excluded, and `CHANGELOG.md` and lockfiles don’t count as shared paths	Warning only: never changes a verdict or the exit code

External PR overlap covers peer PRs from another session, another machine, Dependabot or a human. A peer that merges first can leave a batch PR CONFLICTING, so the warning tells you to settle the merge order. The file lists come from one gh pr list --state open --json number,headRefName,files --limit 100 call. gh returns at most 100 files per PR, so a larger PR can be under-reported. When gh is missing, unauthenticated or the call fails, the report shows one line, Open-PR overlap check skipped: <reason> (the first line of the error), and every other check runs as usual. CHANGELOG.md, package-lock.json, yarn.lock and pnpm-lock.yaml are left out of the comparison, the same list /assess uses for collisions, because nearly every PR touches them.

Base branch. Every check compares against origin/<default branch>, read once per run from origin/HEAD (main when it cannot be read), so a repo whose default is master works. --base is not supported. If a branch’s filesModified diff fails, the report shows an error finding for that branch naming the git command and the batch is BLOCKED, rather than treating the branch as having no changes.

Phase 2: Residual Pattern Detection (`--scan`)

Check	What It Does	Verdict
Residual Pattern Scan	Extracts removed patterns from each PR’s diff, searches codebase for remaining instances	WARN if residuals found

The residual scan uses literal string matching (minimum 8 characters) with git grep. It excludes files already modified by the PR, test files, and node_modules.

Phase 3: AI Briefing (`--review`)

Not yet implemented. Returns a stub message directing you to use --check or --scan.

Common Workflows

Standard Post-Run Verification

After sequant run completes a batch:

# 1. Run merge checks
npx sequant merge --scan

# 2. Review the report
#    READY       → safe to merge
#    NEEDS_ATTENTION → review warnings
#    BLOCKED     → fix before merging

# 3. Merge passing issues
/merger 265 298 299 300

Scripted CI Integration

Use JSON output and exit codes for automation:

npx sequant merge --check --json > report.json
exit_code=$?

if [ $exit_code -eq 0 ]; then
  echo "All clear to merge"
elif [ $exit_code -eq 1 ]; then
  echo "Warnings found — review report.json"
else
  echo "Blocked — fix issues before merging"
fi

Post Findings to PRs

Share results with reviewers by posting to GitHub:

npx sequant merge 265 298 299 300 --scan --post

Each PR receives a per-issue report showing its specific findings and the batch-level verdict.

Report Format

Markdown Output (default)

# Merge Readiness Report

**Generated:** 2026-02-21T19:30:00.000Z
**Batch Verdict:** NEEDS_ATTENTION

## Per-Issue Verdicts

| Issue | Title | Verdict |
|-------|-------|---------|
| #265 | Audit skill files | WARN |
| #298 | Add test tautology | PASS |

## Combined Branch Test
- Lockfile changed in the combined state — reinstalled dependencies with `npm ci`
- `npm run test` passed on combined state
- `npm run build` passed on combined state

## Mirroring
- Modified .claude/skills/qa/SKILL.md but not templates/skills/qa/SKILL.md

## Overlap Detection
- src/commands/run.ts modified by issues #298, #299 (additive)

## External Pr Overlap
- External PR overlap: PR #310 (dependabot/npm_and_yarn/zod-3.25.0) shares package.json with this batch

## Summary
- Errors: 0
- Warnings: 3
- Issues in batch: 4
- Checks run: 4

JSON Output (`--json`)

Returns structured JSON with all check results, per-issue verdicts, and the batch verdict. Useful for scripting and CI integration.

Verdicts

Per-Issue

Verdict	Meaning
PASS	No issues found for this issue
WARN	Warnings found (mirroring gaps, residuals, overlaps)
FAIL	Critical issues (merge conflicts, test/build failures)

Batch-Level

Verdict	Meaning	Exit Code
READY	All issues pass, safe to merge	`0`
NEEDS_ATTENTION	Warnings found, review before merging	`1`
BLOCKED	Critical failures, fix before merging	`2`

Troubleshooting

”No run logs found”

Symptoms: Error when running sequant merge without issue numbers.

Solution: Either specify issues explicitly or run sequant run first to generate a run log:

# Explicit issues
npx sequant merge 265 298 --check

# Or run first
npx sequant run 265 298
npx sequant merge --check

“No feature branches found”

Symptoms: Error saying no branches found for specified issues.

Solution: Ensure feature branches exist — either pushed to remote or in local worktrees:

# Check remote branches
git branch -r | grep feature/265

# Check worktrees
git worktree list

Combined branch test reports merge conflict

Symptoms: BLOCKED verdict due to merge conflict between feature branches.

Solution: This means two feature branches modify the same file in incompatible ways. Options:

Merge one branch first, then rebase the other
Manually resolve the conflict before merging both
If the conflict is in auto-generated files, it may resolve after merging one branch

Mirroring warnings for intentional divergences

Symptoms: WARN for a .claude/skills/ file that intentionally differs from templates/skills/.

Solution: Mirroring warnings are advisory. If the divergence is intentional (e.g., project-specific paths), note it in your PR description and proceed with merge.