sequant 2.3.0 → 2.5.0

package/dist/src/commands/ready-tui-adapter.js

@@ -0,0 +1,130 @@
+/**
+ * Single-issue snapshot adapter for `sequant ready` (#699 Part A).
+ *
+ * The Ink TUI is pull-based: `App` polls `getSnapshot(): RunSnapshot` at 10 Hz
+ * (see `src/ui/tui/index.ts`). But `ready` has no `RunOrchestrator` — its
+ * progress arrives push-style via the gate's `onProgress` hook (#697). This
+ * adapter bridges the two: a small mutable tracker the gate feeds, exposing a
+ * `getSnapshot()` that returns a one-issue `RunSnapshot` for the TUI to mount.
+ *
+ * The gate fires `start`/`complete`/`failed` around each `qa`/`loop` pass; we
+ * model those passes as the phase row, with a coarse `nowLine`
+ * (`formatCoarseNowLine`) — no agent-stream enrichment (a stated Non-Goal).
+ */
+import { formatCoarseNowLine, } from "../lib/workflow/run-state.js";
+/**
+ * Mutable single-issue runtime tracker that doubles as a TUI snapshot provider.
+ *
+ * Lifecycle: construct → mount `renderTui(adapter)` → pass `adapter.onProgress`
+ * to the gate → on gate resolution call `markDone(ready)` so the polling `App`
+ * sees `done` and unmounts.
+ */
+export class ReadySnapshotAdapter {
+    issueNumber;
+    title;
+    branch;
+    qualityLoop;
+    status = "queued";
+    phases = [];
+    currentPhase;
+    startedAt;
+    completedAt;
+    finished = false;
+    constructor(opts) {
+        this.issueNumber = opts.issueNumber;
+        this.title = opts.title;
+        this.branch = opts.branch;
+        this.qualityLoop = opts.qualityLoop ?? true;
+    }
+    /**
+     * `ProgressCallback`-shaped sink wired into the gate's `onProgress`.
+     *
+     * - `start`    → append a running phase + set `currentPhase` (coarse nowLine).
+     * - `complete` → mark the active phase done, record elapsed, clear nowLine.
+     * - `failed`   → mark the active phase failed, flip issue status to failed.
+     * - `activity` → refresh the activity stamp / nowLine if a finer signal lands.
+     */
+    onProgress = (_issue, phase, event, extra) => {
+        const now = new Date();
+        switch (event) {
+            case "start": {
+                if (!this.startedAt)
+                    this.startedAt = now;
+                this.status = "running";
+                this.phases.push({ name: phase, status: "running", startedAt: now });
+                this.currentPhase = {
+                    name: phase,
+                    startedAt: now,
+                    lastActivityAt: now,
+                    nowLine: formatCoarseNowLine(phase),
+                };
+                break;
+            }
+            case "complete":
+            case "failed": {
+                const active = this.phases[this.phases.length - 1];
+                if (active && active.status === "running") {
+                    active.status = event === "failed" ? "failed" : "done";
+                    active.elapsedMs =
+                        extra?.durationSeconds != null
+                            ? Math.round(extra.durationSeconds * 1000)
+                            : active.startedAt
+                                ? now.getTime() - active.startedAt.getTime()
+                                : undefined;
+                }
+                this.currentPhase = undefined;
+                if (event === "failed")
+                    this.status = "failed";
+                break;
+            }
+            case "activity": {
+                if (this.currentPhase) {
+                    this.currentPhase = {
+                        ...this.currentPhase,
+                        lastActivityAt: now,
+                        nowLine: extra?.text?.trim()
+                            ? extra.text.trim()
+                            : this.currentPhase.nowLine,
+                    };
+                }
+                break;
+            }
+        }
+    };
+    /**
+     * Mark the run finished after `runReadyGate` resolves. Flips the snapshot's
+     * `done` flag so the polling `App` unmounts, and sets a terminal status
+     * (failed wins if a phase already failed).
+     */
+    markDone(ready) {
+        this.completedAt = new Date();
+        this.currentPhase = undefined;
+        if (this.status !== "failed") {
+            this.status = ready ? "passed" : "failed";
+        }
+        this.finished = true;
+    }
+    /** Pull-based snapshot consumed by the TUI's 10 Hz poll loop. */
+    getSnapshot() {
+        const issue = {
+            number: this.issueNumber,
+            title: this.title,
+            branch: this.branch,
+            status: this.status,
+            phases: this.phases.map((p) => ({ ...p })),
+            currentPhase: this.currentPhase ? { ...this.currentPhase } : undefined,
+            startedAt: this.startedAt,
+            completedAt: this.completedAt,
+        };
+        return {
+            config: {
+                concurrency: 1,
+                baseBranch: this.branch,
+                qualityLoop: this.qualityLoop,
+            },
+            issues: [issue],
+            done: this.finished,
+            capturedAt: new Date(),
+        };
+    }
+}

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

@@ -0,0 +1,49 @@
+/**
+ * sequant ready <issue> — post-resolve A+ QA gate (#683)
+ *
+ * Runs a full-weight `qa → loop → qa` pipeline against an issue's existing
+ * worktree, reproducing the maintainer's manual fresh-session A+ pass
+ * deterministically, then STOPS at a human merge gate. It NEVER merges.
+ *
+ * Gate policy (flag > settings.ready.policy > "ac"):
+ * - `ac`    (default) — loop until ACs are objectively met; report (not fix)
+ *                        quality gaps and Non-Goal-touching findings.
+ * - `a-plus` (opt-in)  — loop toward READY_FOR_MERGE, auto-fixing quality gaps.
+ *
+ * Terminates in `waiting_for_human_merge` (when ready) or `blocked` (needs
+ * human / no implementation), persists that state, and emits a structured gap
+ * report. See `src/lib/workflow/ready-gate.ts` for the engine.
+ */
+import { type ReadyPolicy } from "../lib/settings.js";
+import { type ReadyResult } from "../lib/workflow/ready-gate.js";
+export interface ReadyCommandOptions {
+    policy?: string;
+    maxIterations?: number;
+    budget?: number;
+    timeout?: number;
+    /** Commander surfaces `--no-mcp` as `mcp === false`. */
+    mcp?: boolean;
+    json?: boolean;
+    verbose?: boolean;
+}
+/**
+ * Exit code from a ready result.
+ * - 0: ready (awaiting human merge)
+ * - 1: not ready — needs human intervention (budget/iterations/stagnation)
+ * - 2: not ready — no implementation (#534) or hard error
+ */
+export declare function getReadyExitCode(result: ReadyResult): number;
+/**
+ * Resolve the gate policy: `--policy` flag > settings.ready.policy > "ac".
+ * Invalid flag values fall back to the settings/default value.
+ *
+ * @internal Exported for testing only.
+ */
+export declare function resolvePolicy(flag: string | undefined, settingsPolicy: ReadyPolicy): ReadyPolicy;
+/**
+ * Locate the worktree path for an issue from `git worktree list`.
+ *
+ * @internal Exported for testing only.
+ */
+export declare function resolveWorktreePath(issueNumber: number): string | null;
+export declare function readyCommand(issueArg: string, options: ReadyCommandOptions): Promise<void>;

package/dist/src/commands/ready.js

@@ -0,0 +1,243 @@
+/**
+ * sequant ready <issue> — post-resolve A+ QA gate (#683)
+ *
+ * Runs a full-weight `qa → loop → qa` pipeline against an issue's existing
+ * worktree, reproducing the maintainer's manual fresh-session A+ pass
+ * deterministically, then STOPS at a human merge gate. It NEVER merges.
+ *
+ * Gate policy (flag > settings.ready.policy > "ac"):
+ * - `ac`    (default) — loop until ACs are objectively met; report (not fix)
+ *                        quality gaps and Non-Goal-touching findings.
+ * - `a-plus` (opt-in)  — loop toward READY_FOR_MERGE, auto-fixing quality gaps.
+ *
+ * Terminates in `waiting_for_human_merge` (when ready) or `blocked` (needs
+ * human / no implementation), persists that state, and emits a structured gap
+ * report. See `src/lib/workflow/ready-gate.ts` for the engine.
+ */
+import { ui, colors } from "../lib/cli-ui.js";
+import { getSettings } from "../lib/settings.js";
+import { listWorktrees } from "../lib/workflow/worktree-manager.js";
+import { GitHubProvider } from "../lib/workflow/platforms/github.js";
+import { getStateManager } from "../lib/workflow/state-manager.js";
+import { executePhaseWithRetry } from "../lib/workflow/phase-executor.js";
+import { buildProgressWiring } from "./run-progress.js";
+import { ReadySnapshotAdapter } from "./ready-tui-adapter.js";
+import { runReadyGate, parseNonGoals, } from "../lib/workflow/ready-gate.js";
+/**
+ * Exit code from a ready result.
+ * - 0: ready (awaiting human merge)
+ * - 1: not ready — needs human intervention (budget/iterations/stagnation)
+ * - 2: not ready — no implementation (#534) or hard error
+ */
+export function getReadyExitCode(result) {
+    if (result.ready)
+        return 0;
+    if (result.reason === "NO_IMPLEMENTATION")
+        return 2;
+    return 1;
+}
+/**
+ * Resolve the gate policy: `--policy` flag > settings.ready.policy > "ac".
+ * Invalid flag values fall back to the settings/default value.
+ *
+ * @internal Exported for testing only.
+ */
+export function resolvePolicy(flag, settingsPolicy) {
+    if (flag === "ac" || flag === "a-plus")
+        return flag;
+    return settingsPolicy;
+}
+/**
+ * Locate the worktree path for an issue from `git worktree list`.
+ *
+ * @internal Exported for testing only.
+ */
+export function resolveWorktreePath(issueNumber) {
+    const match = listWorktrees().find((w) => w.issue === issueNumber);
+    return match?.path ?? null;
+}
+export async function readyCommand(issueArg, options) {
+    const issueNumber = parseInt(issueArg, 10);
+    if (isNaN(issueNumber)) {
+        if (options.json) {
+            console.log(JSON.stringify({ error: `Invalid issue: ${issueArg}` }));
+        }
+        else {
+            console.error(ui.errorBox("Invalid issue", `"${issueArg}" is not a number`));
+        }
+        process.exitCode = 2;
+        return;
+    }
+    const settings = await getSettings();
+    const policy = resolvePolicy(options.policy, settings.ready.policy);
+    const maxIterations = typeof options.maxIterations === "number" && options.maxIterations > 0
+        ? options.maxIterations
+        : settings.run.maxIterations;
+    const tokenBudget = typeof options.budget === "number" && options.budget > 0
+        ? options.budget
+        : undefined;
+    const phaseTimeout = typeof options.timeout === "number" && options.timeout > 0
+        ? options.timeout
+        : settings.run.timeout;
+    const mcp = options.mcp !== false;
+    // Resolve the issue's existing worktree (reuses run/state worktree infra).
+    const worktreePath = resolveWorktreePath(issueNumber);
+    if (!worktreePath) {
+        const msg = `No worktree found for issue #${issueNumber}. ` +
+            `Run \`sequant run ${issueNumber}\` first (or create one with ./scripts/new-feature.sh).`;
+        if (options.json) {
+            console.log(JSON.stringify({ error: msg }));
+        }
+        else {
+            console.error(ui.errorBox("No worktree", msg));
+        }
+        process.exitCode = 2;
+        return;
+    }
+    // Parse the issue's Non-Goals so `ac` mode can mark touching findings
+    // report-only. Best-effort: an unavailable body just yields no Non-Goals.
+    const gh = new GitHubProvider();
+    const body = gh.fetchIssueBodySync(String(issueNumber));
+    const nonGoals = body ? parseNonGoals(body) : [];
+    // Live progress UI (non-`--json` only, so no live writes corrupt piped JSON):
+    //   - TTY      → #699: the boxed Ink TUI, driven by a single-issue snapshot
+    //                adapter fed by the gate's `onProgress` (supersedes #697's
+    //                plain renderer on this path).
+    //   - non-TTY  → #697: the plain phase-matrix renderer, which degrades to
+    //                line mode off a TTY. Static-report fallback, unchanged.
+    const useTui = !options.json && Boolean(process.stdout.isTTY);
+    let renderer = null;
+    let heartbeat = null;
+    let onProgress;
+    let adapter = null;
+    let tuiHandle = null;
+    if (!options.json) {
+        console.log(ui.headerBox("SEQUANT READY"));
+        console.log("");
+        console.log(colors.muted(`Issue #${issueNumber} · policy: ${policy} · max iterations: ${maxIterations}` +
+            (tokenBudget
+                ? ` · budget: ${tokenBudget.toLocaleString()} tokens`
+                : "") +
+            `\nWorktree: ${worktreePath}`));
+        console.log(colors.muted("Full-weight QA (pre-flight checks ON). Never merges — stops at the human gate."));
+        console.log("");
+    }
+    if (useTui) {
+        // Build the snapshot adapter and mount the Ink TUI against it. The gate's
+        // `onProgress` events drive the single box; `markDone` (below) flips the
+        // snapshot's `done` flag so the polling `App` unmounts.
+        const title = gh.fetchIssueTitleSync(String(issueNumber)) ?? `Issue #${issueNumber}`;
+        const branch = listWorktrees().find((w) => w.issue === issueNumber)?.branch ?? "";
+        adapter = new ReadySnapshotAdapter({ issueNumber, title, branch });
+        onProgress = adapter.onProgress;
+        const { renderTui } = await import("../ui/tui/index.js");
+        tuiHandle = renderTui(adapter);
+    }
+    else if (!options.json) {
+        // Stream phases as they fire (no `basePhases`): the ready pipeline length
+        // is dynamic (1–N qa/loop passes), so a fixed seed would leave a stuck-
+        // pending `loop` cell when the gate stops after the first qa.
+        ({ renderer, heartbeat, onProgress } = buildProgressWiring({
+            tuiEnabled: false,
+            quiet: false,
+            issueNumbers: [issueNumber],
+            phaseTimeoutSeconds: phaseTimeout,
+            maxLoopIterations: maxIterations,
+        }));
+    }
+    // SIGINT: tear down the live zone (TUI unmount or renderer dispose) before
+    // ShutdownManager writes its cleanup banner so the two don't collide on
+    // stdout (mirror run.ts SIGINT ordering).
+    const sigintHandler = () => {
+        tuiHandle?.unmount();
+        renderer?.dispose();
+    };
+    if (renderer || tuiHandle)
+        process.once("SIGINT", sigintHandler);
+    // Real phase runner: wraps executePhaseWithRetry against the worktree. The
+    // renderer doubles as the PhasePauseHandle (7th arg) so `--verbose` streaming
+    // pauses/resumes the live zone instead of double-rendering (AC-5).
+    const runPhase = (phase, config, wt) => executePhaseWithRetry(issueNumber, phase, config, undefined, wt, undefined, renderer ?? undefined);
+    let result;
+    try {
+        result = await runReadyGate({
+            issueNumber,
+            worktreePath,
+            policy,
+            maxIterations,
+            tokenBudget,
+            nonGoals,
+            phaseTimeout,
+            mcp,
+            verbose: options.verbose,
+            runPhase,
+            onProgress,
+        });
+    }
+    catch (error) {
+        // Tear down the live zone on the error path too — not just the happy path
+        // (Derived AC: cleanup on ALL exit paths). For the TUI, mark done + unmount
+        // so ink restores the terminal before the error box prints.
+        adapter?.markDone(false);
+        tuiHandle?.unmount();
+        renderer?.dispose();
+        heartbeat?.dispose();
+        if (renderer || tuiHandle)
+            process.off("SIGINT", sigintHandler);
+        const message = error instanceof Error ? error.message : String(error);
+        if (options.json) {
+            console.log(JSON.stringify({ error: message }));
+        }
+        else {
+            console.error(ui.errorBox("Ready gate failed", message));
+        }
+        process.exitCode = 2;
+        return;
+    }
+    // Persist the terminal state so `sequant status` reflects it (Derived AC).
+    // Best-effort: initialize the issue in state if a prior run didn't track it.
+    try {
+        const stateManager = getStateManager();
+        const existing = await stateManager.getIssueState(issueNumber);
+        if (!existing) {
+            const title = gh.fetchIssueTitleSync(String(issueNumber)) ?? `Issue #${issueNumber}`;
+            await stateManager.initializeIssue(issueNumber, title, {
+                worktree: worktreePath,
+            });
+        }
+        await stateManager.updateIssueStatus(issueNumber, result.issueStatus);
+    }
+    catch {
+        // State persistence is non-fatal — the report is the primary output.
+    }
+    if (options.json) {
+        console.log(JSON.stringify({
+            issue: result.issueNumber,
+            policy: result.policy,
+            ready: result.ready,
+            reason: result.reason,
+            status: result.issueStatus,
+            iterations: result.iterations,
+            finalVerdict: result.finalVerdict,
+            autoFixed: result.autoFixed,
+            remaining: result.remaining,
+            tokensUsed: result.tokensUsed,
+        }, null, 2));
+    }
+    else {
+        // #699 AC-3 / #697 AC-6: tear the live zone DOWN before printing the report
+        // so the markdown lands in clean scrollback. For the TUI, flip `done` so the
+        // polling App unmounts, await that unmount (which also emits the durable
+        // teardown summary, AC-5), then print the report below it.
+        if (tuiHandle) {
+            adapter?.markDone(result.ready);
+            await tuiHandle.done;
+        }
+        renderer?.dispose();
+        console.log(result.report);
+    }
+    heartbeat?.dispose();
+    if (renderer || tuiHandle)
+        process.off("SIGINT", sigintHandler);
+    process.exitCode = getReadyExitCode(result);
+}

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

@@ -8,11 +8,14 @@
  */
 import type { RunRenderer } from "../lib/cli-ui/run-renderer-types.js";
 import { LivenessHeartbeat } from "../lib/workflow/heartbeat.js";
-import type { ProgressCallback } from "../lib/workflow/types.js";
+import type { ProgressCallback, PhasePlanCallback } from "../lib/workflow/types.js";
 export interface ProgressWiring {
     renderer: RunRenderer | null;
     heartbeat: LivenessHeartbeat | null;
     onProgress: ProgressCallback | undefined;
+    /** #672 AC-2: forwarded to the orchestrator so batch-executor can hand the
+     *  resolved phase pipeline back to the renderer once it's known. */
+    onPhasePlan: PhasePlanCallback | undefined;
 }
 /**
  * Construct the renderer + heartbeat + onProgress callback for a run.
@@ -27,6 +30,13 @@ export declare function buildProgressWiring(args: {
     /** AC-23: when auto-detect mode is on, the renderer shows `Phase: detecting…`
      *  while spec runs (before the resolved plan is known). */
     autoDetectPhases?: boolean;
+    /** #672 AC-2: the base configured phase pipeline. In explicit-phase mode
+     *  (not auto-detect) this is known upfront, so every issue — including those
+     *  still queued behind the active one — can show its roadmap immediately
+     *  rather than only once it starts running. `setPhasePlan` later refines it
+     *  per issue (e.g. testgen/security-review insertion). Ignored in
+     *  auto-detect mode, where the plan isn't known until spec resolves it. */
+    basePhases?: string[];
     /** #624 Item 3 / D2: total allowed quality-loop iterations (from settings). */
     maxLoopIterations?: number;
 }): ProgressWiring;

package/dist/src/commands/run-progress.js

@@ -14,7 +14,7 @@ import { LivenessHeartbeat } from "../lib/workflow/heartbeat.js";
  * `tuiEnabled` and `quiet` are mutually exclusive with the renderer path.
  */
 export function buildProgressWiring(args) {
-    const { tuiEnabled, quiet, issueNumbers, phaseTimeoutSeconds, autoDetectPhases, maxLoopIterations, } = args;
+    const { tuiEnabled, quiet, issueNumbers, phaseTimeoutSeconds, autoDetectPhases, basePhases, maxLoopIterations, } = args;
     const heartbeat = quiet && !tuiEnabled
         ? new LivenessHeartbeat({ phaseTimeoutSeconds })
         : null;
@@ -36,8 +36,20 @@ export function buildProgressWiring(args) {
         })
         : null;
     if (renderer) {
+        // #672 AC-2: seed the planned pipeline at registration when it's known
+        // upfront (explicit-phase mode). This makes queued issues render their
+        // roadmap before they start, matching the issue's multi-row matrix
+        // mock-up. In auto-detect mode the plan isn't known yet, so we leave
+        // `plannedPhases` undefined and rely on `setPhasePlan` once spec resolves.
+        const seedPlan = !autoDetectPhases && basePhases && basePhases.length > 0
+            ? basePhases
+            : undefined;
         for (const issueNumber of issueNumbers) {
-            renderer.registerIssue({ issueNumber, autoDetect: autoDetectPhases });
+            renderer.registerIssue({
+                issueNumber,
+                autoDetect: autoDetectPhases,
+                plannedPhases: seedPlan,
+            });
         }
     }
     let onProgress;
@@ -72,5 +84,10 @@ export function buildProgressWiring(args) {
                 heartbeat.stop({ issueNumber: issue, phase });
         };
     }
-    return { renderer, heartbeat, onProgress };
+    // #672 AC-2: only the renderer path consumes a phase plan; quiet / TUI
+    // modes leave this undefined and the orchestrator no-ops the callback.
+    const onPhasePlan = renderer
+        ? (issue, phases) => renderer.setPhasePlan(issue, phases)
+        : undefined;
+    return { renderer, heartbeat, onProgress, onPhasePlan };
 }

package/dist/src/commands/run.js

@@ -72,12 +72,15 @@ export async function runCommand(issues, options) {
     const tuiEnabled = Boolean(options.experimentalTui) && Boolean(process.stdout.isTTY);
     // RunRenderer (#618) + LivenessHeartbeat (#574) wiring lives in
     // run-progress.ts to keep this adapter under the 200-LOC cap (#503 AC-2).
-    const { renderer, heartbeat, onProgress } = buildProgressWiring({
+    const { renderer, heartbeat, onProgress, onPhasePlan } = buildProgressWiring({
         tuiEnabled,
         quiet: Boolean(options.quiet),
         issueNumbers: resolved.issueNumbers,
         phaseTimeoutSeconds: settings.run.timeout,
         autoDetectPhases: resolved.autoDetectPhases,
+        // #672 AC-2: base pipeline so queued issues show their roadmap upfront in
+        // explicit-phase mode (ignored when auto-detect resolves the plan later).
+        basePhases: resolved.config.phases,
         // #624 Item 3 / D2: route the resolved maxIterations into the renderer so
         // `(attempt N/M)` and `loop N/M` reflect actual configured limits.
         maxLoopIterations: resolved.config.maxIterations,
@@ -97,6 +100,8 @@ export async function runCommand(issues, options) {
             const result = await RunOrchestrator.run({
                 ...init,
                 onProgress,
+                onPhasePlan,
+                phasePauseHandle: renderer ?? undefined,
                 onOrchestratorReady: (orch) => {
                     tuiHandle = renderTui(orch);
                 },
@@ -121,7 +126,12 @@ export async function runCommand(issues, options) {
     if (renderer)
         process.once("SIGINT", sigintHandler);
     try {
-        const result = await RunOrchestrator.run({ ...init, onProgress }, issues, batches);
+        const result = await RunOrchestrator.run({
+            ...init,
+            onProgress,
+            onPhasePlan,
+            phasePauseHandle: renderer ?? undefined,
+        }, issues, batches);
         // Record PR info in renderer state before summary so done rows show PR #s.
         if (renderer) {
             for (const r of result.results) {

package/dist/src/commands/status.js

@@ -65,6 +65,8 @@ function colorStatus(status, resolvedAt) {
             return chalk.blue(status);
         case "waiting_for_qa_gate":
             return chalk.yellow(status);
+        case "waiting_for_human_merge":
+            return chalk.green(status);
         case "ready_for_merge":
             return chalk.green(status);
         case "merged":
@@ -152,6 +154,7 @@ function displayIssueSummary(issues) {
     const byStatus = {
         in_progress: [],
         waiting_for_qa_gate: [],
+        waiting_for_human_merge: [],
         ready_for_merge: [],
         blocked: [],
         not_started: [],
@@ -165,6 +168,7 @@ function displayIssueSummary(issues) {
     const statusOrder = [
         "in_progress",
         "waiting_for_qa_gate",
+        "waiting_for_human_merge",
         "ready_for_merge",
         "blocked",
         "not_started",

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

@@ -9,6 +9,8 @@ export interface WatchCommandOptions {
     pollIntervalMs?: number;
     /** Abort signal for clean shutdown (tests). */
     signal?: AbortSignal;
+    /** Override cwd for resolving the pid file + archive root (test seam). */
+    cwd?: string;
 }
 export declare function watchCommand(argsAndOptions: {
     args: string[];