sequant 2.11.0 → 2.13.0

package/dist/src/lib/workflow/mutation-marker.js

@@ -0,0 +1,97 @@
+/**
+ * Parseable mutation-verification markers for `/qa` §6i (#939).
+ *
+ * CLAUDE.md's testing rule ("Gate tests ship with a recorded mutation
+ * result") was honor-system prose — nothing parsed or checked the recorded
+ * result, so compliance was invisible (see #830, #834's "prose only, and
+ * therefore unenforceable" defect class). This module promotes that record
+ * to a parseable PR-body marker:
+ *
+ * ```
+ * <!-- SEQUANT_MUTATION: {"ac":"AC-3","mutation":"removed payload fixture
+ * block","failedTest":"injection.test.ts > rejects payload"} -->
+ * ```
+ *
+ * Same durable-marker idiom as `SEQUANT_SPEC` (spec-recommendation.ts) and
+ * `SEQUANT_PHASE` (phase-detection.ts): a flat-JSON HTML comment, matched
+ * with the `{[^}]+}` regex family. That regex stops at the FIRST `}`, so the
+ * payload must stay flat — a nested object would truncate mid-JSON and fail
+ * to parse. Unlike those two markers (one recommendation / one status per
+ * comment, latest-wins), a PR body carries one `SEQUANT_MUTATION` marker per
+ * AC, so all markers are collected, not just the latest.
+ */
+import { z } from "zod";
+import { stripMarkdownCode } from "./phase-detection.js";
+/** Regex to extract mutation-verification marker JSON from HTML comments. */
+const MUTATION_MARKER_REGEX = /<!-- SEQUANT_MUTATION: (\{[^}]+\}) -->/g;
+const MutationMarkerSchema = z.object({
+    ac: z.string().min(1),
+    mutation: z.string().min(1),
+    failedTest: z.string().min(1),
+});
+function parseMarkersRaw(prBody) {
+    const markers = [];
+    const stripped = stripMarkdownCode(prBody);
+    MUTATION_MARKER_REGEX.lastIndex = 0;
+    let match;
+    while ((match = MUTATION_MARKER_REGEX.exec(stripped)) !== null) {
+        let parsed;
+        try {
+            parsed = JSON.parse(match[1]);
+        }
+        catch {
+            continue;
+        }
+        const result = MutationMarkerSchema.safeParse(parsed);
+        if (result.success) {
+            markers.push(result.data);
+        }
+    }
+    return markers;
+}
+export function parseMutationMarkers(prBody, diffTestFiles) {
+    const markers = parseMarkersRaw(prBody);
+    if (diffTestFiles === undefined) {
+        return markers;
+    }
+    return markers.map((marker) => ({
+        ...marker,
+        classification: classifyMutationMarker(marker, diffTestFiles),
+    }));
+}
+/**
+ * Reduce a marker list to one-per-AC, the later marker winning.
+ *
+ * A re-run's marker (e.g. after amending the PR body) supersedes the
+ * earlier one for the same AC — the same "latest wins" idiom
+ * `resolveSpecRecommendation` uses for `SEQUANT_SPEC`.
+ *
+ * @param markers - Markers as returned by {@link parseMutationMarkers}
+ * @returns Map keyed by AC id, one marker per key
+ */
+export function latestMutationMarkerPerAc(markers) {
+    const byAc = new Map();
+    for (const marker of markers) {
+        byAc.set(marker.ac, marker);
+    }
+    return byAc;
+}
+/**
+ * Classify a marker's `failedTest` against the diff's actual test files.
+ *
+ * A fabricated marker (naming a test that doesn't exist in the diff) is
+ * worse than a missing one — it claims verification that never happened.
+ * `failedTest` follows the `<file> > <test name>` shape `/qa` §6i renders
+ * in its output table (e.g. `injection.test.ts > rejects payload`); only
+ * the file segment is checked, since the suite/test-name portion after
+ * ` > ` isn't independently verifiable without executing the test.
+ *
+ * @param marker - A single parsed marker
+ * @param diffTestFiles - Test file paths present in the PR's diff
+ * @returns `"valid"` when the named file is in the diff, `"test_not_in_diff"` otherwise
+ */
+export function classifyMutationMarker(marker, diffTestFiles) {
+    const namedFile = marker.failedTest.split(">")[0]?.trim() ?? "";
+    const found = diffTestFiles.some((file) => file === namedFile || file.endsWith(`/${namedFile}`));
+    return found ? "valid" : "test_not_in_diff";
+}

package/dist/src/lib/workflow/phase-executor.d.ts

@@ -225,6 +225,15 @@ export declare function endedWithoutVerdict(output: string | undefined): boolean
  * @internal Exported for testing only
  */
 export declare function parseQaSummary(output: string): QaSummary | null;
+/**
+ * Select the gap descriptions from a QA summary appropriate to feed a fix
+ * loop (#937 AC-3): every gap, except one whose `SEQUANT_QA_GAPS` finding is
+ * explicitly marked `document` or `pause_for_human` — those are QA-real but
+ * not code-fixable (quality/polish, or a decision the loop can't make on its
+ * own). A gap with no matching finding (the legacy prose-scrape path) is
+ * always included, unchanged from pre-#937 behavior.
+ */
+export declare function selectFixableGaps(summary: QaSummary | null | undefined): string[];
 /**
  * Format duration in human-readable format
  */
@@ -341,6 +350,14 @@ export declare function mapAgentFailureToPhaseResult(phase: Phase, agentResult:
     sessionId?: string;
     resumeHandle?: ResumeHandle;
 };
+/**
+ * Marks the embedded `promptContext` block appended below so a phase's own
+ * skill (e.g. `/loop`) can detect it deterministically instead of pattern-
+ * matching prose that varies per producer (`ready-gate.ts` and
+ * `batch-executor.ts` build differently-worded context for the same slot).
+ * See #960.
+ */
+export declare const PROMPT_CONTEXT_SENTINEL = "SEQUANT_PROMPT_CONTEXT";
 /**
  * Get the prompt for a phase with the issue number substituted.
  * Selects self-contained prompts for non-Claude agents.

package/dist/src/lib/workflow/phase-executor.js

@@ -10,6 +10,7 @@
 import chalk from "chalk";
 import { execFileSync } from "child_process";
 import { resolveDiffBase } from "./git-diff-utils.js";
+import { parseQaGapsMarker } from "./qa-gaps-marker.js";
 import { readAgentsMd } from "../agents-md.js";
 import { getDriver } from "./drivers/index.js";
 import { classifyError } from "./error-classifier.js";
@@ -499,9 +500,43 @@ export function parseQaSummary(output) {
     }
     if (acTotal === 0)
         return null;
-    const gaps = parseListSection(output, /\*\*(?:Issues|Gaps)/);
+    const proseGaps = parseListSection(output, /\*\*(?:Issues|Gaps)/);
     const suggestions = parseListSection(output, /\*\*Suggestions/);
-    return { acMet, acTotal, gaps, suggestions };
+    // #937: prefer the structured marker, but UNION with the prose scrape
+    // rather than replace it — a marker-carrying comment can still contain a
+    // gap the model couldn't fit into the six categories (the fallback rule),
+    // and that prose-only finding must not be silently dropped (AC-5).
+    const findings = parseQaGapsMarker(output) ?? undefined;
+    const seen = new Set();
+    const gaps = [];
+    for (const gap of [
+        ...(findings?.map((f) => f.description) ?? []),
+        ...proseGaps,
+    ]) {
+        const key = gap.trim().toLowerCase();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        gaps.push(gap);
+    }
+    return { acMet, acTotal, gaps, suggestions, ...(findings && { findings }) };
+}
+/**
+ * Select the gap descriptions from a QA summary appropriate to feed a fix
+ * loop (#937 AC-3): every gap, except one whose `SEQUANT_QA_GAPS` finding is
+ * explicitly marked `document` or `pause_for_human` — those are QA-real but
+ * not code-fixable (quality/polish, or a decision the loop can't make on its
+ * own). A gap with no matching finding (the legacy prose-scrape path) is
+ * always included, unchanged from pre-#937 behavior.
+ */
+export function selectFixableGaps(summary) {
+    if (!summary)
+        return [];
+    const excluded = new Set((summary.findings ?? [])
+        .filter((f) => f.recommendedAction === "document" ||
+        f.recommendedAction === "pause_for_human")
+        .map((f) => f.description.trim().toLowerCase()));
+    return summary.gaps.filter((g) => !excluded.has(g.trim().toLowerCase()));
 }
 /**
  * Parse a markdown bullet list section, filtering out "None" variants.
@@ -850,6 +885,14 @@ export function mapAgentFailureToPhaseResult(phase, agentResult, durationSeconds
         exitCode: agentResult.exitCode,
     };
 }
+/**
+ * Marks the embedded `promptContext` block appended below so a phase's own
+ * skill (e.g. `/loop`) can detect it deterministically instead of pattern-
+ * matching prose that varies per producer (`ready-gate.ts` and
+ * `batch-executor.ts` build differently-worded context for the same slot).
+ * See #960.
+ */
+export const PROMPT_CONTEXT_SENTINEL = "SEQUANT_PROMPT_CONTEXT";
 /**
  * Get the prompt for a phase with the issue number substituted.
  * Selects self-contained prompts for non-Claude agents.
@@ -867,9 +910,11 @@ export async function getPhasePrompt(phase, issueNumber, agent, promptContext) {
         : undefined;
     const template = driverPrompt ?? definition.promptTemplate;
     let basePrompt = template.replace(/\{issue\}/g, String(issueNumber));
-    // Append phase-specific context (e.g., QA findings for loop phase)
+    // Append phase-specific context (e.g., QA findings for loop phase),
+    // wrapped in a sentinel so the phase's own skill (e.g. /loop) can detect
+    // embedded orchestrator context without re-fetching it from GitHub (#960).
     if (promptContext) {
-        basePrompt += `\n\n---\n\n${promptContext}`;
+        basePrompt += `\n\n---\n\n<!-- ${PROMPT_CONTEXT_SENTINEL} -->\n${promptContext}\n<!-- /${PROMPT_CONTEXT_SENTINEL} -->`;
     }
     // Include AGENTS.md content in the prompt context for non-Claude agent compatibility.
     // Claude reads CLAUDE.md natively, but other agents (Aider, Codex, Gemini CLI)
@@ -1046,6 +1091,7 @@ async function executePhase(issueNumber, phase, config, resumeHandle, worktreePa
         phaseTimeout: config.phaseTimeout,
         verbose: config.verbose,
         mcp: config.mcp,
+        mcpAllowlist: config.mcpAllowlist,
         resumeHandle: eligibleHandle,
         sessionId: eligibleHandle?.token,
         files,
@@ -1092,10 +1138,18 @@ async function executePhase(issueNumber, phase, config, resumeHandle, worktreePa
         shutdownManager.removeAbortController(abortController);
     }
     const durationSeconds = (Date.now() - startTime) / 1000;
+    // #975: extract the concrete model ID from the driver's modelUsage map.
+    // First key is the primary model dispatched; undefined for drivers that
+    // don't populate modelUsage (aider, subprocess paths).
+    const resolvedModel = agentResult.modelUsage
+        ? Object.keys(agentResult.modelUsage)[0]
+        : undefined;
     if (agentResult.success) {
-        return mapAgentSuccessToPhaseResult(phase, agentResult, durationSeconds, cwd);
+        const result = mapAgentSuccessToPhaseResult(phase, agentResult, durationSeconds, cwd);
+        return resolvedModel ? { ...result, resolvedModel } : result;
     }
-    return mapAgentFailureToPhaseResult(phase, agentResult, durationSeconds);
+    const result = mapAgentFailureToPhaseResult(phase, agentResult, durationSeconds);
+    return resolvedModel ? { ...result, resolvedModel } : result;
 }
 /**
  * Execute a phase with automatic retry for cold-start failures and MCP fallback.

package/dist/src/lib/workflow/qa-gaps-marker.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Parseable structured gap-finding markers for `/qa` (#937).
+ *
+ * `parseQaSummary`'s prose scrape (`parseListSection` against a
+ * `**Issues:**`/`**Gaps**` header) is lossy — it misses AC-table NOT_MET
+ * rows, §6d Adversarial Re-Read findings, and §5 Risk Assessment. QA output
+ * templates now end with a structured marker:
+ *
+ * ```
+ * <!-- SEQUANT_QA_GAPS: {"findings":[{"category":"test_gap","evidence":"...",
+ * "description":"...","recommendedAction":"fix_now"}]} -->
+ * ```
+ *
+ * Same durable-marker idiom as `SEQUANT_SPEC` (spec-recommendation.ts),
+ * `SEQUANT_PHASE` (phase-detection.ts), and `SEQUANT_MUTATION`
+ * (mutation-marker.ts) — but unlike those three, this marker's payload is
+ * an array of objects, not a flat record, so it cannot reuse their
+ * `{[^}]+}` regex (that stops at the FIRST `}`, truncating mid-JSON on any
+ * nested object). Instead this matches lazily up to the closing `-->`,
+ * which the emitting template guarantees appears on the same line as the
+ * marker (single-line JSON, no `-->` inside string values).
+ */
+import { type GapFinding } from "./run-log-schema.js";
+/**
+ * Parse every `SEQUANT_QA_GAPS` marker from a QA comment/output and return
+ * the findings from the last valid one (latest-wins, matching
+ * `resolveSpecRecommendation`'s idiom for `SEQUANT_SPEC`).
+ *
+ * Markers inside fenced code blocks or inline code (e.g. a doc example
+ * showing the marker format) are ignored. Malformed JSON or a
+ * schema-invalid payload is skipped rather than thrown — an unparseable
+ * marker degrades to "no marker found", not a crash.
+ *
+ * @param output - QA comment body or agent output text
+ * @returns The findings array from the last valid marker, or `null` if no
+ *   valid marker was found
+ */
+export declare function parseQaGapsMarker(output: string): GapFinding[] | null;

package/dist/src/lib/workflow/qa-gaps-marker.js

@@ -0,0 +1,66 @@
+/**
+ * Parseable structured gap-finding markers for `/qa` (#937).
+ *
+ * `parseQaSummary`'s prose scrape (`parseListSection` against a
+ * `**Issues:**`/`**Gaps**` header) is lossy — it misses AC-table NOT_MET
+ * rows, §6d Adversarial Re-Read findings, and §5 Risk Assessment. QA output
+ * templates now end with a structured marker:
+ *
+ * ```
+ * <!-- SEQUANT_QA_GAPS: {"findings":[{"category":"test_gap","evidence":"...",
+ * "description":"...","recommendedAction":"fix_now"}]} -->
+ * ```
+ *
+ * Same durable-marker idiom as `SEQUANT_SPEC` (spec-recommendation.ts),
+ * `SEQUANT_PHASE` (phase-detection.ts), and `SEQUANT_MUTATION`
+ * (mutation-marker.ts) — but unlike those three, this marker's payload is
+ * an array of objects, not a flat record, so it cannot reuse their
+ * `{[^}]+}` regex (that stops at the FIRST `}`, truncating mid-JSON on any
+ * nested object). Instead this matches lazily up to the closing `-->`,
+ * which the emitting template guarantees appears on the same line as the
+ * marker (single-line JSON, no `-->` inside string values).
+ */
+import { z } from "zod";
+import { GapFindingSchema } from "./run-log-schema.js";
+import { stripMarkdownCode } from "./phase-detection.js";
+/** Regex to extract the SEQUANT_QA_GAPS marker JSON from an HTML comment. */
+const QA_GAPS_MARKER_REGEX = /<!-- SEQUANT_QA_GAPS: (\{[\s\S]*?\}) -->/g;
+const QaGapsMarkerPayloadSchema = z.object({
+    findings: z.array(GapFindingSchema),
+});
+/**
+ * Parse every `SEQUANT_QA_GAPS` marker from a QA comment/output and return
+ * the findings from the last valid one (latest-wins, matching
+ * `resolveSpecRecommendation`'s idiom for `SEQUANT_SPEC`).
+ *
+ * Markers inside fenced code blocks or inline code (e.g. a doc example
+ * showing the marker format) are ignored. Malformed JSON or a
+ * schema-invalid payload is skipped rather than thrown — an unparseable
+ * marker degrades to "no marker found", not a crash.
+ *
+ * @param output - QA comment body or agent output text
+ * @returns The findings array from the last valid marker, or `null` if no
+ *   valid marker was found
+ */
+export function parseQaGapsMarker(output) {
+    if (!output)
+        return null;
+    const stripped = stripMarkdownCode(output);
+    QA_GAPS_MARKER_REGEX.lastIndex = 0;
+    let latest = null;
+    let match;
+    while ((match = QA_GAPS_MARKER_REGEX.exec(stripped)) !== null) {
+        let parsed;
+        try {
+            parsed = JSON.parse(match[1]);
+        }
+        catch {
+            continue;
+        }
+        const result = QaGapsMarkerPayloadSchema.safeParse(parsed);
+        if (result.success) {
+            latest = result.data.findings;
+        }
+    }
+    return latest;
+}

package/dist/src/lib/workflow/ready-gate.d.ts

@@ -23,7 +23,7 @@
  */
 import type { ExecutionConfig, PhaseResult, ProgressCallback } from "./types.js";
 import { type EscalationRecord } from "./effort-escalation.js";
-import type { QaVerdict } from "./run-log-schema.js";
+import type { QaVerdict, GapCategory, GapAction } from "./run-log-schema.js";
 import type { ReadyPolicy } from "../settings.js";
 import type { IssueStatus } from "./state-schema.js";
 import { type LoopProgressSnapshot } from "./qa-stagnation.js";
@@ -69,6 +69,15 @@ export interface ReadyGapItem {
      * mode these are explicitly report-only (never fed to the fix loop).
      */
     nonGoal: boolean;
+    /**
+     * Structured taxonomy fields from the `SEQUANT_QA_GAPS` marker (#937),
+     * present only when this gap's description matched a marker finding.
+     * A gap surfaced only via the legacy prose scrape carries none of these.
+     */
+    category?: GapCategory;
+    evidence?: string;
+    recommendedAction?: GapAction;
+    affectedAcs?: string[];
 }
 /** Structured outcome of a ready-gate run. */
 export interface ReadyResult {
@@ -117,6 +126,13 @@ export interface RunReadyGateOptions {
     phaseTimeout: number;
     /** Whether MCP servers are enabled for phase execution. */
     mcp: boolean;
+    /**
+     * Claude Desktop MCP server names explicitly opted in (#936). Callers
+     * (`commands/ready.ts`) resolve this from `settings.run.mcpAllowlist` —
+     * see the doc comment on `ExecutionConfig.mcpAllowlist` for why this
+     * producer cannot drift from `buildExecutionConfig`'s own assignment.
+     */
+    mcpAllowlist?: string[];
     verbose?: boolean;
     /** Injectable phase runner — defaults to the real executePhaseWithRetry wrapper. */
     runPhase: ReadyPhaseRunner;
@@ -155,6 +171,14 @@ export interface RunReadyGateOptions {
      * dispatch to decide whether that specific `qa`/`loop` call escalates.
      */
     effortEscalation?: boolean;
+    /**
+     * Persist the final gap report as an issue comment when the gate reaches
+     * a terminal state with a QA verdict (#937 AC-4) — callers wire this to
+     * `GitHubProvider.postComment`. Best-effort: a failure here is caught and
+     * swallowed, never failing the gate itself — `result.report` (returned to
+     * the caller either way) is the primary channel.
+     */
+    postReport?: (body: string) => Promise<void>;
 }
 /**
  * Pure exit predicate. Given a policy and a QA verdict, has the loop reached

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

@@ -138,11 +138,28 @@ export function parseNonGoals(issueBody) {
     }
     return items;
 }
-function classifyGaps(gaps, nonGoals) {
-    return gaps.map((g) => ({
-        description: g,
-        nonGoal: gapTouchesNonGoals(g, nonGoals),
-    }));
+/**
+ * Classify each gap description for the report, enriching with structured
+ * taxonomy fields (#937) when the gap matches a `SEQUANT_QA_GAPS` marker
+ * finding. `findings` are matched to `gaps` by description (trimmed,
+ * case-folded) since `parseQaSummary` already unions marker findings into
+ * `gaps` in document order — every marker finding's description is present.
+ */
+function classifyGaps(gaps, nonGoals, findings) {
+    const byDescription = new Map((findings ?? []).map((f) => [f.description.trim().toLowerCase(), f]));
+    return gaps.map((g) => {
+        const finding = byDescription.get(g.trim().toLowerCase());
+        return {
+            description: g,
+            nonGoal: finding?.nonGoal ?? gapTouchesNonGoals(g, nonGoals),
+            ...(finding && {
+                category: finding.category,
+                evidence: finding.evidence,
+                recommendedAction: finding.recommendedAction,
+                ...(finding.affectedAcs && { affectedAcs: finding.affectedAcs }),
+            }),
+        };
+    });
 }
 function defaultReadTokensUsed(worktreePath) {
     const dir = path.join(worktreePath, TOKEN_USAGE_DIR);
@@ -167,6 +184,7 @@ function buildPhaseConfig(opts, extra) {
         noSmartTests: false,
         dryRun: false,
         mcp: opts.mcp,
+        mcpAllowlist: opts.mcpAllowlist,
         retry: true,
         // #914: producer 2 (see the doc comment on RunReadyGateOptions.phasePolicies
         // for why this can't drift from buildExecutionConfig's own assignment).
@@ -229,14 +247,44 @@ export function formatReadyReport(result) {
     }
     else {
         for (const item of result.remaining) {
-            const tag = item.nonGoal ? " _(Non-Goal — report-only)_" : "";
-            lines.push(`- ${item.description}${tag}`);
+            const tags = [
+                item.category && item.recommendedAction
+                    ? `\`${item.category} · ${item.recommendedAction}\``
+                    : undefined,
+                item.nonGoal ? "_(Non-Goal — report-only)_" : undefined,
+            ].filter(Boolean);
+            const suffix = tags.length > 0 ? ` ${tags.join(" ")}` : "";
+            lines.push(`- ${item.description}${suffix}`);
         }
     }
     lines.push("");
     lines.push("> The human merge gate is intentional: `sequant ready` never merges. Review the gaps above, then merge manually when satisfied.");
+    lines.push("");
+    lines.push(formatReadyGapsMarker(result.remaining));
     return lines.join("\n");
 }
+/**
+ * Render `remaining` as a `SEQUANT_QA_GAPS` marker so the persisted ready
+ * report (#937 AC-4) carries the same machine-readable channel `/qa` itself
+ * emits — only items that came from a structured finding (have a
+ * `category`) round-trip; legacy prose-only gaps are already in the prose
+ * list above and are not re-encoded here.
+ */
+function formatReadyGapsMarker(remaining) {
+    const findings = remaining
+        .filter((g) => g.category !== undefined &&
+        g.evidence !== undefined &&
+        g.recommendedAction !== undefined)
+        .map((g) => ({
+        category: g.category,
+        evidence: g.evidence,
+        description: g.description,
+        recommendedAction: g.recommendedAction,
+        ...(g.affectedAcs && { affectedAcs: g.affectedAcs }),
+        ...(g.nonGoal && { nonGoal: g.nonGoal }),
+    }));
+    return `<!-- SEQUANT_QA_GAPS: ${JSON.stringify({ findings })} -->`;
+}
 /**
  * Drive the policy-bounded `qa → loop → qa` ready gate.
  */
@@ -277,7 +325,7 @@ export async function runReadyGate(opts) {
     // #915: escalated (base, escalated) tiers, one entry per QA-pass dispatch
     // that actually escalated. Populated at the two dispatch sites below.
     const effortEscalations = [];
-    const finish = (reason) => {
+    const finish = async (reason) => {
         const ready = reason === "AC_MET" || reason === "READY_FOR_MERGE";
         const issueStatus = ready
             ? "waiting_for_human_merge"
@@ -297,6 +345,22 @@ export async function runReadyGate(opts) {
             effortEscalations,
         };
         result.report = formatReadyReport(result);
+        // #937 AC-4: persist the gap report as an issue comment once the gate
+        // reaches a terminal state carrying a QA verdict. `finalVerdict === null`
+        // covers NO_IMPLEMENTATION/UNCOMMITTED_ONLY/NO_VERDICT and the guard
+        // TOKEN_BUDGET check before the first QA pass — none of those have a gap
+        // report worth persisting. Best-effort: a post failure must never fail
+        // the gate — `result.report` (returned either way) is the primary
+        // channel, same rationale as `sequant ready`'s existing state-persistence
+        // try/catch.
+        if (result.finalVerdict !== null && opts.postReport) {
+            try {
+                await opts.postReport(result.report);
+            }
+            catch {
+                // Non-fatal — see comment above.
+            }
+        }
         return result;
     };
     const budgetExceeded = () => typeof tokenBudget === "number" &&
@@ -338,7 +402,7 @@ export async function runReadyGate(opts) {
         }
         finalVerdict = verdict;
         const gaps = qaResult.summary?.gaps ?? [];
-        remaining = classifyGaps(gaps, nonGoals);
+        remaining = classifyGaps(gaps, nonGoals, qaResult.summary?.findings);
         // Policy threshold reached → stop at the human merge gate.
         if (isAtThreshold(policy, verdict)) {
             return finish(verdict === "READY_FOR_MERGE" ? "READY_FOR_MERGE" : "AC_MET");
@@ -353,9 +417,15 @@ export async function runReadyGate(opts) {
         // 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.
+        // touching findings are excluded from what we ask the loop to fix, as are
+        // `SEQUANT_QA_GAPS` findings explicitly marked `document` or
+        // `pause_for_human` (#937 AC-3) — a gap with no `recommendedAction` (the
+        // legacy prose-only path) is still treated as fixable, unchanged from
+        // pre-#937 behavior.
         const fixableGaps = remaining
-            .filter((g) => !g.nonGoal)
+            .filter((g) => !g.nonGoal &&
+            g.recommendedAction !== "document" &&
+            g.recommendedAction !== "pause_for_human")
             .map((g) => g.description);
         const before = snapshotFn(worktreePath);
         // #915: iterations > 1 means this fix pass follows a QA pass that was

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

@@ -88,13 +88,15 @@ export function getNextActionHint(issue) {
             if (issue.currentPhase) {
                 const failedPhase = Object.entries(issue.phases).find(([, ps]) => ps.status === "failed");
                 if (failedPhase) {
-                    return `sequant run ${issue.number} --phase ${failedPhase[0]}`;
+                    return `sequant run ${issue.number} --phases ${failedPhase[0]}`;
                 }
             }
             return `sequant run ${issue.number}`;
         }
         case "waiting_for_qa_gate":
-            return `sequant run ${issue.number} --phase qa`;
+            return `sequant run ${issue.number} --phases qa`;
+        case "awaiting_verification":
+            return `sequant run ${issue.number} --phases qa`;
         case "waiting_for_human_merge":
             // `sequant ready` certified the work; a human reviews + merges manually.
             if (issue.pr?.number) {