sequant 2.3.0 → 2.5.0

package/dist/src/lib/workflow/ready-gate.js

@@ -0,0 +1,374 @@
+/**
+ * Ready gate engine (#683).
+ *
+ * Drives the `sequant ready <issue>` pipeline: a full-weight `qa → loop → qa`
+ * loop that reproduces the maintainer's manual fresh-session A+ pass
+ * deterministically, then STOPS at a human merge gate — it never merges.
+ *
+ * The loop's exit threshold is set by a **gate policy**:
+ *
+ * - `ac` (default): stop once no `AC_NOT_MET` verdict remains. Remaining
+ *   quality/polish gaps are surfaced in the report but NOT auto-fixed. Findings
+ *   that touch the issue's Non-Goals are report-only. Predictable, scope-
+ *   respecting behavior for a team engineer with a fixed agenda.
+ * - `a-plus` (opt-in): loop toward `READY_FOR_MERGE`, auto-fixing quality gaps.
+ *
+ * Both policies are additionally bounded by `maxIterations`, an optional token
+ * budget, and the `LOOP_NO_DIFF` stagnation guard. The #534 class (zero-diff
+ * exec / null QA verdict) is never reported as ready.
+ *
+ * This module is the reusable engine — a future `sequant run --ready-gate`
+ * (out of scope for #683) can reuse `runReadyGate` directly. The command shell
+ * lives in `src/commands/ready.ts`.
+ */
+import { snapshotLoopProgress, compareLoopProgress, } from "./qa-stagnation.js";
+import { hasExecChanges } from "./phase-executor.js";
+import { readTokenUsageFiles, aggregateTokenUsage, TOKEN_USAGE_DIR, } from "./token-utils.js";
+import * as path from "path";
+/**
+ * Pure exit predicate. Given a policy and a QA verdict, has the loop reached
+ * its stopping threshold?
+ *
+ * - `READY_FOR_MERGE` always stops (both policies).
+ * - `ac`: `AC_MET_BUT_NOT_A_PLUS` also stops — ACs are objectively met; the
+ *   remaining gaps are quality-only and `ac` reports rather than fixes them.
+ * - `a-plus`: only `READY_FOR_MERGE` stops.
+ * - `AC_NOT_MET` / `NEEDS_VERIFICATION` never stop in either policy.
+ */
+export function isAtThreshold(policy, verdict) {
+    if (verdict === "READY_FOR_MERGE")
+        return true;
+    if (policy === "ac")
+        return verdict === "AC_MET_BUT_NOT_A_PLUS";
+    return false;
+}
+const STOPWORDS = new Set([
+    "the",
+    "and",
+    "for",
+    "with",
+    "that",
+    "this",
+    "from",
+    "into",
+    "are",
+    "was",
+    "has",
+    "have",
+    "not",
+    "but",
+    "its",
+    "via",
+    "any",
+    "all",
+    "out",
+    "should",
+    "would",
+    "could",
+    "when",
+    "then",
+    "than",
+    "must",
+    "will",
+]);
+function significantTokens(text) {
+    return new Set(text
+        .toLowerCase()
+        .replace(/[^a-z0-9\s-]/g, " ")
+        .split(/[\s-]+/)
+        .filter((w) => w.length > 3 && !STOPWORDS.has(w)));
+}
+/**
+ * Does a gap description overlap a Non-Goal? Conservative token-overlap
+ * heuristic: ≥2 shared significant words marks the gap as Non-Goal-touching.
+ *
+ * @internal Exported for testing only.
+ */
+export function gapTouchesNonGoals(gap, nonGoals) {
+    if (nonGoals.length === 0)
+        return false;
+    const gapTokens = significantTokens(gap);
+    if (gapTokens.size === 0)
+        return false;
+    for (const ng of nonGoals) {
+        const ngTokens = significantTokens(ng);
+        let overlap = 0;
+        for (const t of ngTokens) {
+            if (gapTokens.has(t))
+                overlap++;
+            if (overlap >= 2)
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * Parse the issue body's Non-Goals section into a list of bullet items.
+ *
+ * Recognizes `## Non-goals`, `## Non-Goals`, `### Out of scope`, etc. Captures
+ * markdown bullet items until the next heading. Returns `[]` when no section is
+ * present.
+ *
+ * @internal Exported for testing only.
+ */
+export function parseNonGoals(issueBody) {
+    if (!issueBody)
+        return [];
+    const lines = issueBody.split("\n");
+    const items = [];
+    let inSection = false;
+    const headingRe = /^#{1,6}\s+(.*)$/;
+    const nonGoalHeadingRe = /^(non-?goals?|out[ -]of[ -]scope)\b/i;
+    for (const line of lines) {
+        const heading = line.match(headingRe);
+        if (heading) {
+            inSection = nonGoalHeadingRe.test(heading[1].trim());
+            continue;
+        }
+        if (!inSection)
+            continue;
+        const bullet = line.match(/^\s*[-*]\s+(.+)$/);
+        if (bullet) {
+            // Strip surrounding markdown emphasis/backticks for cleaner matching.
+            const text = bullet[1].replace(/[`*]/g, "").trim();
+            if (text)
+                items.push(text);
+        }
+    }
+    return items;
+}
+function classifyGaps(gaps, nonGoals) {
+    return gaps.map((g) => ({
+        description: g,
+        nonGoal: gapTouchesNonGoals(g, nonGoals),
+    }));
+}
+function defaultReadTokensUsed(worktreePath) {
+    const dir = path.join(worktreePath, TOKEN_USAGE_DIR);
+    // Read without cleanup — the engine polls cumulatively across phases.
+    const files = readTokenUsageFiles(dir);
+    return aggregateTokenUsage(files).tokensUsed;
+}
+/**
+ * Build a minimal ExecutionConfig for a single ready-gate phase.
+ */
+function buildPhaseConfig(opts, extra) {
+    return {
+        phases: [],
+        phaseTimeout: opts.phaseTimeout,
+        qualityLoop: false,
+        maxIterations: opts.maxIterations,
+        skipVerification: false,
+        sequential: true,
+        concurrency: 1,
+        parallel: false,
+        verbose: opts.verbose ?? false,
+        noSmartTests: false,
+        dryRun: false,
+        mcp: opts.mcp,
+        retry: true,
+        ...extra,
+    };
+}
+/**
+ * Render the structured gap report (AC-4).
+ *
+ * @internal Exported for testing only.
+ */
+export function formatReadyReport(result) {
+    const headline = result.ready
+        ? "✅ READY — awaiting human merge decision"
+        : result.reason === "NO_IMPLEMENTATION"
+            ? "⛔ NOT READY — no implementation detected"
+            : "⚠️ NOT READY — needs human intervention";
+    const reasonText = {
+        AC_MET: "Acceptance Criteria are objectively met (no AC_NOT_MET). Remaining gaps are quality-only and reported below (policy `ac` does not auto-fix them).",
+        READY_FOR_MERGE: "QA returned READY_FOR_MERGE.",
+        MAX_ITERATIONS: "Hit the iteration cap before reaching the policy threshold. A human should review the remaining gaps.",
+        TOKEN_BUDGET: "Token budget exhausted before reaching the policy threshold. A human should review the remaining gaps.",
+        LOOP_NO_DIFF: "The fix loop made no diff (stagnation guard). Manual intervention required.",
+        LOOP_FAILED: "The fix loop phase failed. A human should investigate before merging.",
+        NO_IMPLEMENTATION: "Zero-diff worktree or null/unparseable QA verdict — there is nothing to certify (#534 guard).",
+    };
+    const lines = [];
+    lines.push(`## sequant ready — Issue #${result.issueNumber}`);
+    lines.push("");
+    lines.push(`**${headline}**`);
+    lines.push("");
+    lines.push(`- **Policy:** \`${result.policy}\``);
+    lines.push(`- **Final verdict:** ${result.finalVerdict ?? "(none)"}`);
+    lines.push(`- **Stop reason:** ${result.reason} — ${reasonText[result.reason]}`);
+    lines.push(`- **QA passes:** ${result.iterations}`);
+    lines.push(`- **Tokens used:** ${result.tokensUsed.toLocaleString()}`);
+    lines.push(`- **Final state:** \`${result.issueStatus}\` (never auto-merged)`);
+    lines.push("");
+    lines.push("### Auto-fixed");
+    if (result.autoFixed.length === 0) {
+        lines.push("- None");
+    }
+    else {
+        for (const item of result.autoFixed)
+            lines.push(`- ${item}`);
+    }
+    lines.push("");
+    lines.push("### Remaining / accepted gaps");
+    if (result.remaining.length === 0) {
+        lines.push("- None");
+    }
+    else {
+        for (const item of result.remaining) {
+            const tag = item.nonGoal ? " _(Non-Goal — report-only)_" : "";
+            lines.push(`- ${item.description}${tag}`);
+        }
+    }
+    lines.push("");
+    lines.push("> The human merge gate is intentional: `sequant ready` never merges. Review the gaps above, then merge manually when satisfied.");
+    return lines.join("\n");
+}
+/**
+ * Drive the policy-bounded `qa → loop → qa` ready gate.
+ */
+export async function runReadyGate(opts) {
+    const { issueNumber, worktreePath, policy, maxIterations, tokenBudget, nonGoals = [], } = opts;
+    const readTokensUsed = opts.readTokensUsed ?? defaultReadTokensUsed;
+    const hasChangesFn = opts.hasChangesFn ?? hasExecChanges;
+    const snapshotFn = opts.snapshotFn ?? snapshotLoopProgress;
+    // #697: run a phase while emitting live-progress events around it. `iteration`
+    // is the 1-based QA-pass index so the renderer can render `loop N/M`. Emits
+    // `failed` (and re-throws) if the runner itself throws so the catch path in
+    // ready.ts disposes a renderer that already reflects the failed cell.
+    const runPhaseTracked = async (phase, config, iteration) => {
+        opts.onProgress?.(opts.issueNumber, phase, "start", { iteration });
+        let phaseResult;
+        try {
+            phaseResult = await opts.runPhase(phase, config, worktreePath);
+        }
+        catch (err) {
+            opts.onProgress?.(opts.issueNumber, phase, "failed", {
+                iteration,
+                error: err instanceof Error ? err.message : String(err),
+            });
+            throw err;
+        }
+        opts.onProgress?.(opts.issueNumber, phase, phaseResult.success === false ? "failed" : "complete", {
+            iteration,
+            durationSeconds: phaseResult.durationSeconds,
+            error: phaseResult.success === false ? phaseResult.error : undefined,
+        });
+        return phaseResult;
+    };
+    let iterations = 0;
+    let finalVerdict = null;
+    const autoFixed = [];
+    let remaining = [];
+    let tokensUsed = 0;
+    const finish = (reason) => {
+        const ready = reason === "AC_MET" || reason === "READY_FOR_MERGE";
+        const issueStatus = ready
+            ? "waiting_for_human_merge"
+            : "blocked";
+        const result = {
+            issueNumber,
+            policy,
+            ready,
+            reason,
+            issueStatus,
+            iterations,
+            finalVerdict,
+            autoFixed,
+            remaining,
+            tokensUsed,
+            report: "",
+        };
+        result.report = formatReadyReport(result);
+        return result;
+    };
+    const budgetExceeded = () => typeof tokenBudget === "number" &&
+        tokenBudget > 0 &&
+        tokensUsed >= tokenBudget;
+    // Loop is bounded by maxIterations QA passes. Each iteration: run QA, check
+    // the policy threshold + #534 guards, and (if not stopping) run one fix loop.
+    while (iterations < maxIterations) {
+        if (budgetExceeded()) {
+            return finish("TOKEN_BUDGET");
+        }
+        iterations++;
+        const qaResult = await runPhaseTracked("qa", buildPhaseConfig(opts, { fullQa: true }), iterations);
+        tokensUsed = readTokensUsed(worktreePath);
+        const verdict = qaResult.verdict ?? null;
+        // #534 guard: a null/unparseable verdict is never "ready".
+        if (!verdict) {
+            return finish("NO_IMPLEMENTATION");
+        }
+        // #534 guard: an empty worktree (no commits, no uncommitted work) is never
+        // "ready" — replays the #529/#570 empty-branch class.
+        if (!hasChangesFn(worktreePath)) {
+            return finish("NO_IMPLEMENTATION");
+        }
+        finalVerdict = verdict;
+        const gaps = qaResult.summary?.gaps ?? [];
+        remaining = classifyGaps(gaps, nonGoals);
+        // Policy threshold reached → stop at the human merge gate.
+        if (isAtThreshold(policy, verdict)) {
+            return finish(verdict === "READY_FOR_MERGE" ? "READY_FOR_MERGE" : "AC_MET");
+        }
+        // Not at threshold and out of iterations → clean halt, needs human.
+        if (iterations >= maxIterations) {
+            return finish("MAX_ITERATIONS");
+        }
+        if (budgetExceeded()) {
+            return finish("TOKEN_BUDGET");
+        }
+        // Run one fix loop. In `ac` mode we only reach here on AC_NOT_MET, so the
+        // gaps are AC gaps — feeding them via failedAcs keeps the loop scoped to
+        // the AC boundary (quality gaps are never fixed under `ac`). Non-Goal-
+        // touching findings are excluded from what we ask the loop to fix.
+        const fixableGaps = remaining
+            .filter((g) => !g.nonGoal)
+            .map((g) => g.description);
+        const before = snapshotFn(worktreePath);
+        const loopResult = await runPhaseTracked("loop", buildPhaseConfig(opts, {
+            lastVerdict: verdict,
+            failedAcs: fixableGaps.join("; ") || undefined,
+            promptContext: buildLoopContext(policy, verdict, fixableGaps),
+        }), iterations);
+        tokensUsed = readTokensUsed(worktreePath);
+        if (!loopResult.success) {
+            return finish("LOOP_FAILED");
+        }
+        const after = snapshotFn(worktreePath);
+        const progress = compareLoopProgress(before, after);
+        if (!progress.progressed) {
+            return finish("LOOP_NO_DIFF");
+        }
+        // The loop produced a diff — record what it was asked to fix and re-QA.
+        for (const g of fixableGaps) {
+            if (!autoFixed.includes(g))
+                autoFixed.push(g);
+        }
+    }
+    // Iteration cap reached without an explicit stop above (defensive).
+    return finish("MAX_ITERATIONS");
+}
+/**
+ * Build the prompt context handed to the `/loop` phase. Mirrors the
+ * batch-executor's `buildLoopContext` shape but scopes the instruction to the
+ * gate policy so `ac` runs do not chase quality-only gaps.
+ */
+function buildLoopContext(policy, verdict, fixableGaps) {
+    const parts = [];
+    parts.push(`Ready gate (#683) — policy: ${policy}`);
+    parts.push(`QA Verdict: ${verdict}`);
+    if (policy === "ac") {
+        parts.push("Scope: fix ONLY the unmet Acceptance Criteria below. Do NOT address quality/polish gaps or anything touching the issue's Non-Goals — those are deliberately deferred under the `ac` policy.");
+    }
+    else {
+        parts.push("Scope: drive the work toward READY_FOR_MERGE by addressing the gaps below.");
+    }
+    if (fixableGaps.length > 0) {
+        parts.push("Gaps to address:");
+        for (const g of fixableGaps)
+            parts.push(`- ${g}`);
+    }
+    return parts.join("\n");
+}

package/dist/src/lib/workflow/reconcile.js

@@ -95,6 +95,12 @@ export function getNextActionHint(issue) {
         }
         case "waiting_for_qa_gate":
             return `sequant run ${issue.number} --phase qa`;
+        case "waiting_for_human_merge":
+            // `sequant ready` certified the work; a human reviews + merges manually.
+            if (issue.pr?.number) {
+                return `review gaps, then gh pr merge ${issue.pr.number}`;
+            }
+            return `review gaps, then merge manually`;
         case "ready_for_merge":
             if (issue.pr?.number) {
                 return `gh pr merge ${issue.pr.number}`;

package/dist/src/lib/workflow/run-log-schema.d.ts

@@ -113,17 +113,7 @@ export type QaSummary = z.infer<typeof QaSummarySchema>;
  * Log entry for a single phase execution
  */
 export declare const PhaseLogSchema: z.ZodObject<{
-    phase: z.ZodEnum<{
-        qa: "qa";
-        loop: "loop";
-        verify: "verify";
-        spec: "spec";
-        "security-review": "security-review";
-        exec: "exec";
-        testgen: "testgen";
-        test: "test";
-        merger: "merger";
-    }>;
+    phase: z.ZodString;
     issueNumber: z.ZodNumber;
     startTime: z.ZodString;
     endTime: z.ZodString;
@@ -199,17 +189,7 @@ export declare const IssueLogSchema: z.ZodObject<{
         partial: "partial";
     }>;
     phases: z.ZodArray<z.ZodObject<{
-        phase: z.ZodEnum<{
-            qa: "qa";
-            loop: "loop";
-            verify: "verify";
-            spec: "spec";
-            "security-review": "security-review";
-            exec: "exec";
-            testgen: "testgen";
-            test: "test";
-            merger: "merger";
-        }>;
+        phase: z.ZodString;
         issueNumber: z.ZodNumber;
         startTime: z.ZodString;
         endTime: z.ZodString;
@@ -280,17 +260,7 @@ export type IssueLog = z.infer<typeof IssueLogSchema>;
  * Run configuration
  */
 export declare const RunConfigSchema: z.ZodObject<{
-    phases: z.ZodArray<z.ZodEnum<{
-        qa: "qa";
-        loop: "loop";
-        verify: "verify";
-        spec: "spec";
-        "security-review": "security-review";
-        exec: "exec";
-        testgen: "testgen";
-        test: "test";
-        merger: "merger";
-    }>>;
+    phases: z.ZodArray<z.ZodString>;
     sequential: z.ZodBoolean;
     qualityLoop: z.ZodBoolean;
     maxIterations: z.ZodNumber;
@@ -319,17 +289,7 @@ export declare const RunLogSchema: z.ZodObject<{
     startTime: z.ZodString;
     endTime: z.ZodString;
     config: z.ZodObject<{
-        phases: z.ZodArray<z.ZodEnum<{
-            qa: "qa";
-            loop: "loop";
-            verify: "verify";
-            spec: "spec";
-            "security-review": "security-review";
-            exec: "exec";
-            testgen: "testgen";
-            test: "test";
-            merger: "merger";
-        }>>;
+        phases: z.ZodArray<z.ZodString>;
         sequential: z.ZodBoolean;
         qualityLoop: z.ZodBoolean;
         maxIterations: z.ZodNumber;
@@ -346,17 +306,7 @@ export declare const RunLogSchema: z.ZodObject<{
             partial: "partial";
         }>;
         phases: z.ZodArray<z.ZodObject<{
-            phase: z.ZodEnum<{
-                qa: "qa";
-                loop: "loop";
-                verify: "verify";
-                spec: "spec";
-                "security-review": "security-review";
-                exec: "exec";
-                testgen: "testgen";
-                test: "test";
-                merger: "merger";
-            }>;
+            phase: z.ZodString;
             issueNumber: z.ZodNumber;
             startTime: z.ZodString;
             endTime: z.ZodString;

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

@@ -6,13 +6,14 @@
  *
  * @module
  */
-import type { ExecutionConfig, IssueResult, RunOptions, ProgressCallback } from "./types.js";
+import type { ExecutionConfig, IssueResult, RunOptions, ProgressCallback, PhasePlanCallback, PhasePauseHandle } from "./types.js";
 import type { RunSnapshot } from "./run-state.js";
 import type { WorktreeInfo } from "./worktree-manager.js";
 import { LogWriter } from "./log-writer.js";
 import { StateManager } from "./state-manager.js";
 import { ShutdownManager } from "../shutdown.js";
 import type { LockFile } from "../locks/index.js";
+import { WorkflowEventEmitter } from "./event-emitter.js";
 import type { SequantSettings } from "../settings.js";
 /**
  * Build the stack-manifest line emitted into PR bodies under --stacked.
@@ -56,6 +57,14 @@ export interface OrchestratorConfig {
     baseBranch?: string;
     /** Per-phase progress callback (parallel mode) */
     onProgress?: ProgressCallback;
+    /** #672 AC-2: phase-plan callback forwarded into per-issue contexts. */
+    onPhasePlan?: PhasePlanCallback;
+    /**
+     * Optional live-zone pause handle (#656). Forwarded to every issue's
+     * batch context so `executePhaseWithRetry` can quiesce the renderer
+     * around verbose Claude streaming.
+     */
+    phasePauseHandle?: PhasePauseHandle;
 }
 /**
  * High-level init config for full lifecycle execution.
@@ -75,6 +84,15 @@ export interface RunInit {
     baseBranch?: string;
     /** Per-phase progress callback */
     onProgress?: ProgressCallback;
+    /** #672 AC-2: phase-plan callback. Fired once per issue once the executor
+     * has resolved the final phase pipeline. */
+    onPhasePlan?: PhasePlanCallback;
+    /**
+     * Optional live-zone pause handle (#656). Threaded through to the
+     * `OrchestratorConfig` so verbose Claude streaming pauses the renderer's
+     * live zone instead of redrawing over it.
+     */
+    phasePauseHandle?: PhasePauseHandle;
     /**
      * Invoked once the orchestrator is constructed but before execution begins.
      * Used by the experimental TUI to attach a snapshot poller to the active
@@ -146,8 +164,16 @@ export declare class RunOrchestrator {
     private readonly cfg;
     private readonly issueStates;
     private readonly phaseStartTimes;
+    private readonly emitter;
     private done;
     constructor(config: OrchestratorConfig);
+    /**
+     * Returns the workflow event emitter. External consumers (TUI, MCP server,
+     * future webhooks) call `getEmitter().on(...)` to subscribe to lifecycle
+     * events. Subscribing is opt-in — the orchestrator runs unaware of who is
+     * listening (#504, AC-3).
+     */
+    getEmitter(): WorkflowEventEmitter;
     /**
      * Point-in-time view of the entire run.
      *
@@ -157,7 +183,11 @@ export declare class RunOrchestrator {
      * observing torn writes.
      */
     getSnapshot(): RunSnapshot;
-    /** Mark the run as completed so the dashboard can unmount. */
+    /**
+     * Mark the run as completed so the dashboard can unmount and drop event
+     * subscribers. Drains the emitter to prevent leaks across multiple
+     * `run()` invocations in the same process (e.g. the MCP server).
+     */
     markDone(): void;
     private initIssueStates;
     private wrapProgress;