sequant 2.11.0 → 2.12.0

package/dist/src/lib/mcp-config.js

@@ -8,6 +8,7 @@ import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
 import { getVersion } from "./version.js";
+import { getMcpServersConfig } from "./system.js";
 /** Path to the project-level MCP config file used by Claude Code */
 export const PROJECT_MCP_JSON = ".mcp.json";
 /**
@@ -59,6 +60,56 @@ export function getSequantMcpConfig(options) {
     }
     return config;
 }
+/**
+ * Build the MCP server set for an autonomous phase agent (#936).
+ *
+ * Phase agents are a different trust domain from the interactive Claude
+ * Desktop app: they run unattended, and Claude Desktop configs cannot use
+ * `${VAR}` references, so they hold literal secrets that the SDK would
+ * otherwise serialize verbatim into the child process's `--mcp-config`
+ * argv. This builder allowlists instead of passing through — it unions the
+ * project's own `.mcp.json` (secret-free by convention, committed to git)
+ * with a guaranteed sequant server entry, and never reads
+ * `claude_desktop_config.json` **unless** a server name is explicitly
+ * listed in `opts.desktopAllowlist` (from `settings.run.mcpAllowlist`) —
+ * the deliberate per-server opt-in for a desktop-only server. A name not
+ * present in the desktop config is silently ignored.
+ *
+ * @param cwd - Directory to resolve `.mcp.json` from (the phase worktree)
+ * @param opts.desktopAllowlist - Exact `mcpServers` keys to pass through
+ *   from Claude Desktop config, despite the default exclusion
+ * @returns MCP server configurations for the phase agent
+ */
+export function getPhaseMcpServersConfig(cwd, opts) {
+    const mcpJsonPath = path.resolve(cwd ?? ".", PROJECT_MCP_JSON);
+    let servers = {};
+    try {
+        const content = fs.readFileSync(mcpJsonPath, "utf-8");
+        const config = JSON.parse(content);
+        if (config.mcpServers &&
+            typeof config.mcpServers === "object" &&
+            !Array.isArray(config.mcpServers)) {
+            servers = config.mcpServers;
+        }
+    }
+    catch {
+        // .mcp.json doesn't exist or is invalid — sequant entry still applies
+    }
+    const allowedDesktopServers = {};
+    if (opts?.desktopAllowlist && opts.desktopAllowlist.length > 0) {
+        const desktopServers = getMcpServersConfig() ?? {};
+        for (const name of opts.desktopAllowlist) {
+            if (desktopServers[name]) {
+                allowedDesktopServers[name] = desktopServers[name];
+            }
+        }
+    }
+    return {
+        ...allowedDesktopServers,
+        ...servers,
+        sequant: getSequantMcpConfig(),
+    };
+}
 /**
  * Detect which MCP-compatible clients are installed
  */

package/dist/src/lib/scope/analyzer.d.ts

@@ -73,6 +73,10 @@ export declare function detectFeatures(criteria: AcceptanceCriterion[], title: s
  *
  * Looks for a "Non-Goals" or "Out of Scope" section with checkbox items.
  *
+ * Fenced code blocks are excluded before matching (#947 sibling) — a
+ * Non-Goals example shown inside a fence (e.g. illustrating checkbox
+ * syntax) must not itself be read as a real non-goal item.
+ *
  * @param issueBody - Full issue body markdown
  * @returns Non-goals extraction result
  */

package/dist/src/lib/scope/analyzer.js

@@ -16,6 +16,7 @@
  * ```
  */
 import { DEFAULT_SCOPE_CONFIG } from "./types.js";
+import { stripFencedLines } from "../markdown-fence.js";
 /**
  * Keywords for clustering AC items by functional area
  */
@@ -247,14 +248,19 @@ export function detectFeatures(criteria, title) {
  *
  * Looks for a "Non-Goals" or "Out of Scope" section with checkbox items.
  *
+ * Fenced code blocks are excluded before matching (#947 sibling) — a
+ * Non-Goals example shown inside a fence (e.g. illustrating checkbox
+ * syntax) must not itself be read as a real non-goal item.
+ *
  * @param issueBody - Full issue body markdown
  * @returns Non-goals extraction result
  */
 export function parseNonGoals(issueBody) {
     const items = [];
+    const strippedBody = stripFencedLines(issueBody);
     // Find Non-Goals section (case-insensitive)
     const sectionPattern = /##\s*(?:Non[- ]?Goals|Out\s+of\s+Scope|Scope\s+Boundaries)\s*\n([\s\S]*?)(?=\n##|\n---|$)/i;
-    const sectionMatch = issueBody.match(sectionPattern);
+    const sectionMatch = strippedBody.match(sectionPattern);
     if (!sectionMatch) {
         return {
             items: [],

package/dist/src/lib/settings.d.ts

@@ -117,11 +117,35 @@ export interface RunSettings {
     defaultBase?: string;
     /**
      * Enable MCP servers in headless mode.
-     * When true, reads MCP config from Claude Desktop and passes to SDK.
+     * When true, injects the sequant MCP server plus any servers declared in
+     * the project's own `.mcp.json` — never a passthrough of the user's Claude
+     * Desktop config, which is a different trust domain and may carry literal
+     * secrets (#936), unless a server is explicitly named in `mcpAllowlist`
+     * below.
      * When false or --no-mcp flag is used, MCPs are disabled.
      * Default: true
      */
     mcp: boolean;
+    /**
+     * Explicit per-server opt-in to pass specific Claude Desktop MCP servers
+     * through to phase execution (#936).
+     *
+     * `mcp` above never reads Claude Desktop config by default — phase agents
+     * get the sequant server plus the project's own `.mcp.json` only. This is
+     * the deliberate escape hatch for a server that exists only in Claude
+     * Desktop config (e.g. never committed to git): list its exact
+     * `mcpServers` key here and phase agents additionally receive it. A name
+     * not present in the desktop config is silently ignored — this is a
+     * filter, not a requirement. Unset or empty (default): no desktop servers
+     * pass through, matching `mcp`'s secure-by-default behavior.
+     *
+     * ⚠️ Desktop Claude configs cannot use `${VAR}` references, so a server you
+     * allowlist here may carry a literal secret that reaches the phase
+     * process's argv (the SDK serializes `mcpServers` into `--mcp-config`).
+     * Only allowlist a server with no credential, or one whose credential you
+     * accept exposing to phase agents and to `ps`.
+     */
+    mcpAllowlist?: string[];
     /**
      * Enable automatic retry with MCP fallback.
      * When true (default), failed phases are retried with MCP disabled.
@@ -198,6 +222,15 @@ export interface RunSettings {
      * default). See `effort-escalation.ts` for the resolver.
      */
     effortEscalation: boolean;
+    /**
+     * Whether `/fullsolve`'s Phase 5.3 merges the PR automatically once QA
+     * passes (#958). Default `false` — the workflow stops at PR creation +
+     * final summary, preserving the human merge gate kept by #817–#819.
+     * Overridable per-invocation with `--auto-merge`. Read directly by the
+     * `/fullsolve` skill prose (not by any runtime code path — `sequant run`
+     * never merges regardless of this setting).
+     */
+    autoMerge: boolean;
 }
 /**
  * Scope assessment threshold configuration
@@ -373,6 +406,7 @@ export declare const RunSettingsSchema: z.ZodObject<{
     }, z.core.$strip>>;
     defaultBase: z.ZodOptional<z.ZodString>;
     mcp: z.ZodDefault<z.ZodBoolean>;
+    mcpAllowlist: z.ZodOptional<z.ZodArray<z.ZodString>>;
     retry: z.ZodDefault<z.ZodBoolean>;
     autoWaitMinutes: z.ZodDefault<z.ZodNumber>;
     staleBranchThreshold: z.ZodDefault<z.ZodNumber>;
@@ -397,6 +431,7 @@ export declare const RunSettingsSchema: z.ZodObject<{
         }>>;
     }, z.core.$strip>>>;
     effortEscalation: z.ZodDefault<z.ZodBoolean>;
+    autoMerge: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strip>;
 /** Zod schema for ScopeThreshold (base — fields required, no defaults) */
 export declare const ScopeThresholdSchema: z.ZodObject<{
@@ -477,6 +512,7 @@ export declare const SettingsSchema: z.ZodObject<{
         }, z.core.$strip>>;
         defaultBase: z.ZodOptional<z.ZodString>;
         mcp: z.ZodDefault<z.ZodBoolean>;
+        mcpAllowlist: z.ZodOptional<z.ZodArray<z.ZodString>>;
         retry: z.ZodDefault<z.ZodBoolean>;
         autoWaitMinutes: z.ZodDefault<z.ZodNumber>;
         staleBranchThreshold: z.ZodDefault<z.ZodNumber>;
@@ -501,6 +537,7 @@ export declare const SettingsSchema: z.ZodObject<{
             }>>;
         }, z.core.$strip>>>;
         effortEscalation: z.ZodDefault<z.ZodBoolean>;
+        autoMerge: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strip>>;
     agents: z.ZodDefault<z.ZodObject<{
         parallel: z.ZodDefault<z.ZodBoolean>;

package/dist/src/lib/settings.js

@@ -78,6 +78,7 @@ export const RunSettingsSchema = z.object({
     rotation: RotationSettingsSchema.default(() => RotationSettingsSchema.parse({})),
     defaultBase: z.string().optional(),
     mcp: z.boolean().default(true),
+    mcpAllowlist: z.array(z.string()).optional(),
     retry: z.boolean().default(true),
     autoWaitMinutes: z.number().min(0).default(0),
     staleBranchThreshold: z.number().default(5),
@@ -104,6 +105,12 @@ export const RunSettingsSchema = z.object({
      * `effort-escalation.ts` for the resolver.
      */
     effortEscalation: z.boolean().default(false),
+    /**
+     * Whether `/fullsolve`'s Phase 5.3 merges the PR automatically once QA
+     * passes (#958). Default `false` — preserves the human merge gate kept by
+     * #817–#819. Overridable per-invocation with `--auto-merge`.
+     */
+    autoMerge: z.boolean().default(false),
 });
 /** Zod schema for ScopeThreshold (base — fields required, no defaults) */
 export const ScopeThresholdSchema = z.object({
@@ -216,6 +223,7 @@ const KNOWN_KEYS = {
         "rotation",
         "defaultBase",
         "mcp",
+        "mcpAllowlist",
         "retry",
         "staleBranchThreshold",
         "resolvedIssueTTL",
@@ -451,6 +459,7 @@ export const DEFAULT_SETTINGS = {
         resolvedIssueTTL: 7, // Auto-prune resolved issues after 7 days
         relay: true, // Enable interactive relay (#383) by default
         effortEscalation: false, // #915: off by default — raises token spend
+        autoMerge: false, // #958: off by default — preserves the human merge gate
     },
     agents: DEFAULT_AGENT_SETTINGS,
     scopeAssessment: DEFAULT_SCOPE_ASSESSMENT_SETTINGS,
@@ -581,6 +590,10 @@ export function generateSettingsJsonc(settings) {
     lines.push(`    "smartTests": ${JSON.stringify(settings.run.smartTests)},`);
     lines.push(`    // Enable MCP servers in headless mode`);
     lines.push(`    "mcp": ${JSON.stringify(settings.run.mcp)},`);
+    if (settings.run.mcpAllowlist !== undefined) {
+        lines.push(`    // Desktop MCP servers explicitly allowlisted for phases`);
+        lines.push(`    "mcpAllowlist": ${JSON.stringify(settings.run.mcpAllowlist)},`);
+    }
     lines.push(`    // Enable automatic retry with MCP fallback`);
     lines.push(`    "retry": ${JSON.stringify(settings.run.retry)},`);
     lines.push(`    // Commits behind main before warning`);
@@ -698,6 +711,7 @@ Generated by \`sequant init\`. See defaults below.
 | \`smartTests\` | boolean | \`true\` | Enable smart test detection |
 | \`defaultBase\` | string | — | Default base branch for worktree creation |
 | \`mcp\` | boolean | \`true\` | Enable MCP servers in headless mode |
+| \`mcpAllowlist\` | string[] | — | Desktop MCP server names to pass through to phases despite \`mcp\`'s default exclusion (#936) |
 | \`retry\` | boolean | \`true\` | Enable automatic retry with MCP fallback |
 | \`staleBranchThreshold\` | number | \`5\` | Commits behind main before warning |
 | \`resolvedIssueTTL\` | number | \`7\` | Days before resolved issues auto-prune (0=never, -1=immediate) |

package/dist/src/lib/system.d.ts

@@ -54,9 +54,13 @@ export interface McpServerConfig {
 /**
  * Get full MCP server configurations from Claude Desktop config
  *
- * Returns the complete mcpServers object suitable for passing to the
- * Claude Agent SDK query() options. Returns undefined if config doesn't
- * exist or is invalid (graceful degradation for AC-3).
+ * For interactive `doctor` diagnostics only — reports what's configured for
+ * the human user. Never pass this to phase execution (#936): Claude Desktop
+ * is a different trust domain (interactive, human-supervised) than an
+ * autonomous phase agent, and desktop configs carry literal secrets since
+ * they cannot use `${VAR}` references. Phase agents use
+ * `getPhaseMcpServersConfig` from `mcp-config.ts` instead, which allowlists
+ * from the project's own `.mcp.json`.
  *
  * @returns MCP server configurations or undefined
  */

package/dist/src/lib/system.js

@@ -136,9 +136,13 @@ export function getConfiguredMcpServers() {
 /**
  * Get full MCP server configurations from Claude Desktop config
  *
- * Returns the complete mcpServers object suitable for passing to the
- * Claude Agent SDK query() options. Returns undefined if config doesn't
- * exist or is invalid (graceful degradation for AC-3).
+ * For interactive `doctor` diagnostics only — reports what's configured for
+ * the human user. Never pass this to phase execution (#936): Claude Desktop
+ * is a different trust domain (interactive, human-supervised) than an
+ * autonomous phase agent, and desktop configs carry literal secrets since
+ * they cannot use `${VAR}` references. Phase agents use
+ * `getPhaseMcpServersConfig` from `mcp-config.ts` instead, which allowlists
+ * from the project's own `.mcp.json`.
  *
  * @returns MCP server configurations or undefined
  */

package/dist/src/lib/test-tautology-detector.js

@@ -390,12 +390,20 @@ const PROJECT_SCRIPT_PATTERN = /\b(?:hooks\/[\w.-]+\.sh|scripts\/[\w./-]+)/;
  * across declarations, and must reach one of the two markers. Spawning a
  * *system* binary (`git`, `bash` with a temp fixture) matches neither, which
  * is the intended exclusion — those are not this project's code.
+ *
+ * An optional type annotation is allowed between the name and `=`, e.g.
+ *   const HOOK_COPIES: Array<[label: string, path: string]> = [...];
+ * The annotation submatch (`[^=;]*`) stops at the first `=`, so an arrow-
+ * function-typed annotation (`const f: (x: string) => void = ...`) breaks
+ * the match at its `=>` instead of reaching the real assignment — accepted
+ * as a narrow miss; typed function-value declarations are not the shape this
+ * collector targets (path-bearing table/tuple declarations are).
  */
 function collectBuildOutputVars(content) {
     const names = new Set();
     const patterns = [
-        /(?:const|let|var)\s+(\w+)\s*=\s*[^;]*?\bdist\//g,
-        /(?:const|let|var)\s+(\w+)\s*=\s*[^;]*?\b(?:hooks\/[\w.-]+\.sh|scripts\/[\w./-]+)/g,
+        /(?:const|let|var)\s+(\w+)\s*(?::[^=;]*)?=\s*[^;]*?\bdist\//g,
+        /(?:const|let|var)\s+(\w+)\s*(?::[^=;]*)?=\s*[^;]*?\b(?:hooks\/[\w.-]+\.sh|scripts\/[\w./-]+)/g,
     ];
     for (const pattern of patterns) {
         let match;
@@ -405,6 +413,44 @@ function collectBuildOutputVars(content) {
     }
     return [...names];
 }
+/**
+ * Collect callback parameter names bound to a build-output table's rows via
+ * `describe.each(X)("...", (a, b) => {...})`, when `X` is itself a
+ * build-output source: a var already collected by collectBuildOutputVars, or
+ * an inline array literal containing a build-output token directly.
+ *
+ * `describe.each` destructures each table row into positional callback
+ * params. A helper spawning `hookPath` — the param, not the table var — is
+ * exercising production code just as much as one spawning `HOOK_COPIES`
+ * directly; static analysis of the table alone misses it entirely. The
+ * string-title argument is matched by quote char (not `[^()]*`) because test
+ * titles routinely contain literal parens (e.g. `"... (#564) [%s]"`), which
+ * a paren-excluding class would truncate on.
+ *
+ * Bounded like the rest of this file's helper matchers: no nested parens in
+ * the table-var/params captures, so a callback with a destructured or
+ * default-valued param is skipped rather than mis-parsed.
+ */
+function collectDescribeEachParams(content, buildOutputVars) {
+    const names = new Set();
+    const pattern = /describe\.each\(\s*([^()]*?)\s*\)\s*\(\s*(['"`])(?:(?!\2)[\s\S])*?\2\s*,\s*(?:async\s+)?\(([^()]*)\)\s*=>/g;
+    let match;
+    while ((match = pattern.exec(content)) !== null) {
+        const tableArg = match[1].trim();
+        const isKnownVar = /^\w+$/.test(tableArg) && buildOutputVars.includes(tableArg);
+        const isInlineSource = BUILD_OUTPUT_PATTERN.test(tableArg) ||
+            PROJECT_SCRIPT_PATTERN.test(tableArg);
+        if (!isKnownVar && !isInlineSource)
+            continue;
+        for (const param of match[3].split(",")) {
+            const name = param.trim().split(":")[0].trim();
+            if (/^\w+$/.test(name)) {
+                names.add(name);
+            }
+        }
+    }
+    return [...names];
+}
 /**
  * Whether a code body references a build-output token: either the literal
  * `dist/` marker or one of the collected build-path variable names.
@@ -588,7 +634,8 @@ export function analyzeTestFile(content, filePath) {
     }
     try {
         const importedFunctions = extractImports(content);
-        const buildOutputVars = collectBuildOutputVars(content);
+        const declaredBuildOutputVars = collectBuildOutputVars(content);
+        const buildOutputVars = declaredBuildOutputVars.concat(collectDescribeEachParams(content, declaredBuildOutputVars));
         const productionHandles = collectProductionHandles(content, buildOutputVars, importedFunctions);
         const testBlocks = extractTestBlocks(content);
         const analyzedBlocks = testBlocks.map((block) => ({

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

@@ -8,7 +8,7 @@
  * creation).
  */
 import { LogWriter } from "./log-writer.js";
-import { ExecutionConfig, PhaseResult, IssueResult, type RunOptions, type IssueExecutionContext, type BatchExecutionContext, type ProgressCallback } from "./types.js";
+import { ExecutionConfig, PhaseResult, IssueResult, type RunOptions, type IssueExecutionContext, type BatchExecutionContext, type ProgressCallback, type QaVerdict, type QaSummary } from "./types.js";
 import { type ErrorCategory } from "./error-classifier.js";
 export type { RunOptions, ProgressCallback, IssueExecutionContext, BatchExecutionContext, } from "./types.js";
 /**
@@ -205,4 +205,23 @@ export declare function billingHaltReason(result: PhaseResult): string;
  * @internal Exported for testing
  */
 export declare function windowHaltResumeAtMs(result: PhaseResult): number | null;
+/**
+ * Build the comment body for a standard-qa-phase verdict post (#964).
+ * Includes AC coverage and any gaps/suggestions from the parsed `QaSummary`,
+ * plus a machine marker so a future dedup pass has an anchor.
+ * @internal Exported for testing.
+ */
+export declare function buildQaVerdictComment(verdict: QaVerdict, summary: QaSummary | undefined, commitHash: string | undefined, iteration: number): string;
+/**
+ * Post the qa-verdict comment for a standard (non-ready-gate) qa phase under
+ * orchestrated `sequant run` (#964). This is the channel `qa/SKILL.md` §9
+ * promises ("orchestrator handles aggregated summary") but batch-executor
+ * never backed — a re-run producing a fresh, different verdict left a stale,
+ * contradicted comment as the only externally-visible one.
+ *
+ * Best-effort: a post failure is caught and logged, never fails the run —
+ * mirrors {@link runReadyGateForIssue}'s `postReport` contract (#937 AC-4).
+ * @internal Exported for testing.
+ */
+export declare function postQaVerdictComment(issueNumber: number, verdict: QaVerdict, summary: QaSummary | undefined, commitHash: string | undefined, iteration: number, log: (msg: string) => void, postComment?: (issueNumber: number, body: string) => Promise<void>): Promise<void>;
 export declare function runIssueWithLogging(ctx: IssueExecutionContext): Promise<IssueResult>;

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

@@ -14,7 +14,7 @@ import { withEscalatedEffort } from "./effort-escalation.js";
 import { classifyError, errorTypeToCategory, } from "./error-classifier.js";
 import { getGitDiffStats, getCommitHash, resolveDiffBase, } from "./git-diff-utils.js";
 import { createCheckpointCommit, rebaseBeforePR, createPR, readCacheMetrics, filterResumedPhases, } from "./worktree-manager.js";
-import { AUTO_WAIT_BUFFER_MS, createAutoWaitLedger, executePhaseWithRetry, hasExecChanges, isWindowExhaustedRateLimit, } from "./phase-executor.js";
+import { AUTO_WAIT_BUFFER_MS, createAutoWaitLedger, executePhaseWithRetry, hasExecChanges, isWindowExhaustedRateLimit, selectFixableGaps, } from "./phase-executor.js";
 import { BillingError, RateLimitError, resetsAtToMs } from "../errors.js";
 import { parseBodyDependencyMarkers } from "./dependency-markers.js";
 import { determinePhasesForIssue, DOCS_LABELS } from "./phase-mapper.js";
@@ -135,8 +135,11 @@ export function buildLoopContext(failedResult) {
     if (failedResult.verdict) {
         parts.push(`QA Verdict: ${failedResult.verdict}`);
     }
-    if (failedResult.summary?.gaps?.length) {
-        parts.push(`QA Gaps:\n${failedResult.summary.gaps.map((gap) => `- ${gap}`).join("\n")}`);
+    // #937 AC-3: exclude findings marked `document`/`pause_for_human` — those
+    // are QA-real but not something a fix loop should chase.
+    const fixableGaps = selectFixableGaps(failedResult.summary);
+    if (fixableGaps.length) {
+        parts.push(`QA Gaps:\n${fixableGaps.map((gap) => `- ${gap}`).join("\n")}`);
     }
     if (failedResult.summary?.suggestions?.length) {
         parts.push(`Suggestions:\n${failedResult.summary.suggestions.map((s) => `- ${s}`).join("\n")}`);
@@ -564,6 +567,50 @@ async function recordWindowHaltState(stateManager, issueNumber, phase, result) {
         // State tracking errors shouldn't stop execution
     }
 }
+/**
+ * Build the comment body for a standard-qa-phase verdict post (#964).
+ * Includes AC coverage and any gaps/suggestions from the parsed `QaSummary`,
+ * plus a machine marker so a future dedup pass has an anchor.
+ * @internal Exported for testing.
+ */
+export function buildQaVerdictComment(verdict, summary, commitHash, iteration) {
+    const lines = [`## QA Verdict: ${verdict}`];
+    if (summary) {
+        lines.push("", `AC coverage: ${summary.acMet}/${summary.acTotal} met`);
+        if (summary.gaps.length > 0) {
+            lines.push("", "**Gaps:**", ...summary.gaps.map((g) => `- ${g}`));
+        }
+        if (summary.suggestions.length > 0) {
+            lines.push("", "**Suggestions:**", ...summary.suggestions.map((s) => `- ${s}`));
+        }
+    }
+    lines.push("", `<!-- SEQUANT_QA_VERDICT: ${JSON.stringify({
+        verdict,
+        commit: commitHash ?? null,
+        iteration,
+    })} -->`);
+    return lines.join("\n");
+}
+/**
+ * Post the qa-verdict comment for a standard (non-ready-gate) qa phase under
+ * orchestrated `sequant run` (#964). This is the channel `qa/SKILL.md` §9
+ * promises ("orchestrator handles aggregated summary") but batch-executor
+ * never backed — a re-run producing a fresh, different verdict left a stale,
+ * contradicted comment as the only externally-visible one.
+ *
+ * Best-effort: a post failure is caught and logged, never fails the run —
+ * mirrors {@link runReadyGateForIssue}'s `postReport` contract (#937 AC-4).
+ * @internal Exported for testing.
+ */
+export async function postQaVerdictComment(issueNumber, verdict, summary, commitHash, iteration, log, postComment = (n, body) => new GitHubProvider().postComment(String(n), body)) {
+    try {
+        const body = buildQaVerdictComment(verdict, summary, commitHash, iteration);
+        await postComment(issueNumber, body);
+    }
+    catch (err) {
+        log(chalk.yellow(`    !  Failed to post QA verdict comment: ${err}`));
+    }
+}
 /**
  * Run the post-QA ready gate (#817) for a single issue at the run path's
  * post-success / pre-PR seam.
@@ -594,6 +641,8 @@ async function runReadyGateForIssue(args) {
     const getSettingsFn = args.getSettingsFn ?? getSettings;
     const fetchBody = args.fetchBody ??
         ((n) => new GitHubProvider().fetchIssueBodySync(String(n)));
+    const postComment = args.postComment ??
+        ((n, body) => new GitHubProvider().postComment(String(n), body));
     try {
         const settings = await getSettingsFn();
         const policy = settings.ready.policy;
@@ -620,6 +669,8 @@ async function runReadyGateForIssue(args) {
             verbose: config.verbose,
             runPhase,
             onProgress,
+            // #937 AC-4: persist the final gap report as an issue comment.
+            postReport: (body) => postComment(issueNumber, body),
         });
         log(result.ready
             ? chalk.green(`  ✓ Ready gate: ${result.reason} — awaiting human merge (never merged)`)
@@ -636,7 +687,7 @@ async function runReadyGateForIssue(args) {
 }
 export async function runIssueWithLogging(ctx) {
     // Destructure context for use throughout the function
-    const { issueNumber, config, options, title: issueTitle, labels, services: { logWriter, stateManager, shutdownManager }, worktree, chain, packageManager, baseBranch, onProgress, onPhasePlan, phasePauseHandle, } = ctx;
+    const { issueNumber, config, options, title: issueTitle, labels, services: { logWriter, stateManager, shutdownManager }, worktree, chain, packageManager, baseBranch, onProgress, onPhasePlan, phasePauseHandle, postComment: injectedPostComment, } = ctx;
     const worktreePath = worktree?.path;
     const branch = worktree?.branch;
     const chainMode = chain?.enabled;
@@ -1103,6 +1154,23 @@ export async function runIssueWithLogging(ctx) {
                     /* progress errors must not halt */
                 }
             }
+            // #964: post the verdict from a standard (non-ready-gate) qa phase.
+            // qa/SKILL.md §9 promises "the orchestrator handles aggregated summary"
+            // under SEQUANT_ORCHESTRATOR, but nothing backed that promise — a
+            // re-run producing a fresh, different verdict left the stale prior
+            // comment as the only externally-visible one. Gating on
+            // `result.success && result.verdict` also excludes turn-capped and
+            // unparseable-verdict phases (AC-4) without extra bookkeeping, since
+            // both already flow through the `else` branch above.
+            if (phase === "qa" && result.success && result.verdict) {
+                const verdictDiffBase = worktreePath
+                    ? resolveDiffBase(worktreePath, baseBranch ?? "main")
+                    : undefined;
+                const verdictCommitHash = worktreePath && verdictDiffBase
+                    ? getCommitHash(worktreePath, verdictDiffBase)
+                    : undefined;
+                await postQaVerdictComment(issueNumber, result.verdict, result.summary, verdictCommitHash, iteration, log, injectedPostComment);
+            }
             // Log phase result with observability data (AC-1, AC-2, AC-3, AC-7)
             if (logWriter) {
                 // Resolve the diff base once (#878): worktrees branch from
@@ -1222,10 +1290,14 @@ export async function runIssueWithLogging(ctx) {
                     // Build enriched config for loop phase with QA context (#488).
                     // Pass verdict, failed ACs, and error directly so the /loop skill
                     // doesn't need to reconstruct context from GitHub comments.
+                    // #937 AC-3: exclude `document`/`pause_for_human`-tagged findings
+                    // from what the loop is told to fix (same filter as ready-gate's
+                    // fixableGaps).
+                    const fixableGaps = selectFixableGaps(result.summary);
                     const loopConfig = {
                         ...issueConfig,
                         lastVerdict: result.verdict ?? undefined,
-                        failedAcs: result.summary?.gaps?.join("; ") ?? undefined,
+                        failedAcs: fixableGaps.length ? fixableGaps.join("; ") : undefined,
                         promptContext: buildLoopContext(result),
                     };
                     const loopStartTime = new Date();

package/dist/src/lib/workflow/config-resolver.js

@@ -285,6 +285,7 @@ export function buildExecutionConfig(mergedOptions, settings, issueCount) {
         maxIterations: positiveOr(mergedOptions.maxIterations, positiveOr(settings.run.maxIterations, DEFAULT_CONFIG.maxIterations)),
         noSmartTests: mergedOptions.noSmartTests ?? false,
         mcp: mcpEnabled,
+        mcpAllowlist: settings.run.mcpAllowlist,
         retry: retryEnabled,
         // #804: default 0 (off) — the whole regression contract for auto-wait is
         // that an unset flag leaves the #761/#799 halt path untouched.

package/dist/src/lib/workflow/drivers/agent-driver.d.ts

@@ -32,6 +32,13 @@ export interface AgentExecutionConfig {
     phaseTimeout: number;
     verbose: boolean;
     mcp: boolean;
+    /**
+     * Claude Desktop MCP server names explicitly opted in to pass through to
+     * this phase, despite `mcp`'s default exclusion (#936). Forwarded
+     * verbatim to `getPhaseMcpServersConfig`'s `desktopAllowlist` by
+     * ClaudeCodeDriver; ignored by drivers without an MCP concept.
+     */
+    mcpAllowlist?: string[];
     /**
      * Resume a previous session (driver-specific; ignored if unsupported).
      *

package/dist/src/lib/workflow/drivers/claude-code.js

@@ -5,7 +5,7 @@
  * orchestration layer should import the SDK directly.
  */
 import { query } from "@anthropic-ai/claude-agent-sdk";
-import { getMcpServersConfig } from "../../system.js";
+import { getPhaseMcpServersConfig } from "../../mcp-config.js";
 import { RateLimitError, BillingError, createRateLimitError, isWaitableWindow, isRateLimitFailureInfo, } from "../../errors.js";
 import { RingBuffer } from "../ring-buffer.js";
 export class ClaudeCodeDriver {
@@ -80,8 +80,14 @@ export class ClaudeCodeDriver {
             resumeToken = undefined;
         }
         try {
-            // Get MCP servers config if enabled
-            const mcpServers = config.mcp ? getMcpServersConfig() : undefined;
+            // Get MCP servers config if enabled — allowlisted, not passed through
+            // from Claude Desktop config (#936), except for servers explicitly
+            // named in config.mcpAllowlist (settings.run.mcpAllowlist).
+            const mcpServers = config.mcp
+                ? getPhaseMcpServersConfig(config.cwd, {
+                    desktopAllowlist: config.mcpAllowlist,
+                })
+                : undefined;
             const queryInstance = query({
                 prompt,
                 options: {