Ready Command

Quick Start: After a resolve finishes, run sequant ready <issue> to reproduce the maintainer’s manual fresh-session A+ QA pass deterministically. It drives the issue’s worktree through a full-weight qa → loop → qa pipeline, surfaces every gap in a structured report, and stops at the human merge gate — it never merges.

Access

Command: npx sequant ready <issue> [options]
Requirements:
- The issue already has a worktree (i.e. sequant run <issue> ran first).
- GitHub CLI authenticated (gh auth login) — used to read the issue’s Non-Goals.
Relationship: Runs AFTER a resolve (sequant run / /fullsolve), BEFORE a human merges.

sequant run 712          # implement
sequant ready 712        # full-weight A+ gate (this command) — stops, never merges
gh pr merge 712          # human decides

Why it exists

A study of the maintainer’s standalone /qa second looks found that a second pass often catches what the first QA pass accepted. The original 2026-05-30 figure is not reproducible from the surviving transcripts; the reproducible figure is 10 of 27 reviews (37%) caught a would-ship bug. 7 of those 10 landed only after the human’s “any gaps?” follow-up and 3 in the first verdict; none needed a step that orchestrated QA skips. Most of the value is therefore the follow-up pass, which sequant ready automates (dataset). The design also closes two structural gaps, although no catch in the reconstructed set depended on the first:

Orchestrated QA trusts the orchestrator’s git state and skips the branch-freshness / process-state pre-flight checks — exactly the no-implementation / divergent-branch class.
The fullsolve QA loop stops at “good enough” (AC_MET_BUT_NOT_A_PLUS) and never drives toward A+.

sequant ready closes both: it runs QA at full standalone weight (the pre-flight checks execute even under an orchestrator) and loops to a policy-selected threshold — while preserving the human merge decision.

Gate policy (configurable rigor)

The loop’s exit threshold is set by a policy, not hardcoded:

Policy	Loops until	Quality / polish gaps	Audience
`ac` (default)	no `AC_NOT_MET` remains (ACs objectively met)	documented in the report, NOT auto-fixed	team engineer, fixed agenda, predictable diff
`a-plus` (opt-in)	`READY_FOR_MERGE`	auto-fixed in the loop	solo maintainer / max-quality

ac is the default deliberately: “ACs met” is an objective stop condition (the written checklist), whereas a-plus auto-loops everything and risks scope creep, an unpredictable stop condition, and noise. ac still runs the full-weight QA + adversarial re-read, so every gap is surfaced in the report — it just stops fixing at the AC boundary.
In ac mode, any finding that touches the issue’s Non-Goals is explicitly report-only (never fed to the fix loop).
Resolution precedence: --policy flag > ready.policy in .sequant/settings.json > default "ac".

Usage

Drive an issue to merge-readiness (default `ac` policy)

npx sequant ready 712

Opt into the max-quality A+ loop

npx sequant ready 712 --policy a-plus

Cap the loop and emit JSON

npx sequant ready 712 --max-iterations 4 --budget 300000 --json

Options

Flag	Description
`--policy <ac\|a-plus>`	Gate policy. Overrides `ready.policy` in settings. Invalid values fall back to settings/default.
`--max-iterations <n>`	Max QA passes before halting for human review (default: `run.maxIterations`). Whole number ≥ 1.
`--budget <tokens>`	Token budget; on exhaustion the command halts cleanly with a “needs human” message rather than looping. Whole number ≥ 1 — `10k` is rejected, not read as `10` (#833).
`--timeout <seconds>`	Per-phase timeout (default: `run.timeout`). Whole seconds only — `30m` and `abc` are rejected rather than read as `30` (#833).
`--no-mcp`	Disable MCP server injection in headless mode.
`--models <spec>`	Per-phase model override for the qa/loop phases this gate runs (bare value or `phase=model` pairs, e.g. `qa=sonnet`). CLI > `run.phases` settings > absent — see Per-Phase Model & Effort.
`--efforts <spec>`	Per-phase reasoning-effort override (`low\|medium\|high\|xhigh\|max`), same grammar as `--models`.
`--escalate-effort`	On a QA-pass retry (pass ≥ 2), run that pass’s `qa`/`loop` dispatch one reasoning-effort tier above its resolved base. CLI > `run.effortEscalation` settings > `false` — see Effort Escalation on Retries.
`--json`	Emit a structured JSON result instead of the markdown report.
`-v, --verbose`	Verbose phase output.

Termination & guards

The loop terminates on the first of:

Policy threshold reached — ac: no AC_NOT_MET; a-plus: READY_FOR_MERGE. → state waiting_for_human_merge, exit 0.
maxIterations — clean “needs human” halt. → state blocked, exit 1.
Token budget — clean halt on exhaustion. → state blocked, exit 1.
LOOP_NO_DIFF — the fix loop made no commit and no working-tree change (stagnation guard). → state blocked, exit 1.
No implementation (#534 guard) — a zero-diff worktree (empty branch, the #529/#570 class) or a null/unparseable QA verdict is never reported ready. → state blocked, exit 2.

Exit codes

Scripting and CI can gate on the exit code:

0 — ready (awaiting the human merge gate).
1 — not ready, needs human intervention: iteration/budget cap hit, stagnation guard tripped, or a NO_VERDICT QA turn (#853) — the implementation may exist, so this is a re-run case.
2 — nothing certifiable exists on the branch: NO_IMPLEMENTATION (no commits, #534), UNCOMMITTED_ONLY (work exists but was never committed, so it cannot rebase, push, or become a PR — #879), or a hard error (invalid issue, uninitialized project).

Live progress

The gate runs a qa → loop → qa pipeline that can take several minutes. What you see while it runs depends on where output is going:

Interactive terminal (a TTY, no --json) — a boxed live dashboard: a single rounded box for the issue with an animated spinner, the worktree branch, and a phase row that fills in as each pass completes (✓ qa 04s ▸ ✓ loop 03s ▸ ✓ qa 02s). The box repaints in place; long titles/branches truncate to fit, so it stays clean on narrow (≤80-col) terminals and inside tmux. When the gate finishes, the live box is torn down and replaced by:
- a durable one-line summary that stays in scrollback — ✔ #<issue> <title> (or ✘ if it ended not-ready), and
- the full gap report (below), printed in clean scrollback beneath it.
--json, or output that isn’t a TTY (piped, redirected, CI logs) — no live UI is drawn (so it never corrupts piped JSON or log files). You get only the final static report (or JSON).

There is nothing to configure — the dashboard is automatic on a TTY and silently skipped otherwise. NO_COLOR is respected.

Output

A structured gap report (markdown, or --json) containing:

Headline + stop reason — ready vs. needs-human vs. no-implementation.
Final verdict and QA pass count.
Auto-fixed — gaps the fix loop addressed across iterations.
Remaining / accepted gaps — quality gaps (under ac) and Non-Goal items, tagged report-only. Each gap carries the structured taxonomy from /qa’s findings marker (#937): a category (requirement_gap, dependency_gap, test_gap, repository_gap, risk_gap, execution_gap), evidence, and a recommended action — the fix loop only attempts fix_now findings, never ones QA marked document or pause_for_human.
Final state — waiting_for_human_merge or blocked. Reflected by sequant status.

Under the ac policy, once the gate reaches a terminal state carrying a QA verdict, the final gap report (including the findings marker) is also posted as a comment on the issue — so the outcome survives terminal scrollback. Posting is best-effort: a failed comment never fails the gate.

The human merge gate is intentional and permanent: sequant ready never merges. Review the gaps, then merge manually when satisfied.

Non-goals

--from-pr <N> (reverse PR→issue resolution) — a follow-up, not yet supported.
sequant run --ready-gate flag integration — a follow-up; reuses this engine (runReadyGate).
Auto-merge of any kind — the human merge gate is deliberate.