sequant 2.11.0 → 2.13.0

package/dist/src/lib/mcp-config.d.ts

@@ -4,6 +4,7 @@
  * Detects installed MCP clients (Claude Desktop, Cursor, VS Code)
  * and generates appropriate configuration entries for Sequant MCP server.
  */
+import { type McpServerConfig } from "./system.js";
 /** Path to the project-level MCP config file used by Claude Code */
 export declare const PROJECT_MCP_JSON = ".mcp.json";
 /**
@@ -38,6 +39,29 @@ export declare function getSequantMcpConfig(options?: {
     projectDir?: string;
     clientType?: McpClientType;
 }): Record<string, unknown>;
+/**
+ * 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 declare function getPhaseMcpServersConfig(cwd?: string, opts?: {
+    desktopAllowlist?: string[];
+}): Record<string, McpServerConfig>;
 /**
  * Detect which MCP-compatible clients are installed
  */

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

@@ -40,14 +40,14 @@ export interface AgentSettings {
      */
     parallel: boolean;
     /**
-     * Default model for sub-agents.
-     * Options: "haiku" (cheapest), "sonnet" (balanced), "opus" (most capable)
+     * Default model for sub-agents (free string — any alias or dated ID accepted).
      * Default: "haiku" — currently inert per anthropics/claude-code#43869.
+     * See `run.modelRoles` for semantic role indirection (#975).
      * @deprecated currently inert; see anthropics/claude-code#43869. Subagents
      * inherit the parent session's model regardless of this value. Kept so
      * existing user settings.json files continue to parse without error.
      */
-    model: "haiku" | "sonnet" | "opus";
+    model: string;
     /**
      * Isolate parallel agent groups in separate worktrees.
      * When true, each agent in a parallel group gets its own sub-worktree,
@@ -64,6 +64,23 @@ export interface AgentSettings {
  * two validation points cannot drift apart on which values are accepted.
  */
 export declare const EFFORT_LEVELS: readonly ["low", "medium", "high", "xhigh", "max"];
+/**
+ * Map of semantic role names to model strings, used by `run.modelRoles` (#975).
+ *
+ * A value is either:
+ * - a plain string shorthand — desugars to `{ "claude-code": value }` (claude-code driver only)
+ * - an object keyed by driver registry name, for cross-driver mappings
+ *
+ * Role references use a `role:` prefix in phase policy / ladder entries;
+ * bare strings pass through verbatim (AC-3 backward compat).
+ */
+export declare const ModelRolesSchema: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
+export type ModelRoles = z.infer<typeof ModelRolesSchema>;
+/**
+ * Shipped default role map (#975). Family aliases only — no dated model IDs.
+ * Claude-code shorthand form; no opencode/aider entries shipped by default.
+ */
+export declare const DEFAULT_MODEL_ROLES: ModelRoles;
 /**
  * A single phase's `model`/`effort` override for the claude-code driver
  * (#914). See `RunSettings.phases`.
@@ -117,11 +134,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 +239,26 @@ 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;
+    /**
+     * Map of semantic role names to model strings (#975).
+     *
+     * Config expresses **roles**; this map resolves roles to concrete model
+     * strings. Phase policy, ladder, and other model-referencing surfaces use
+     * `role:<name>` to reference an entry; bare strings pass through verbatim.
+     *
+     * Default: `{ fast: "sonnet", strong: "opus", frontier: "fable" }`.
+     * `sequant setup` writes nothing here — absent key → defaults apply.
+     */
+    modelRoles: ModelRoles;
 }
 /**
  * Scope assessment threshold configuration
@@ -329,11 +390,7 @@ export declare const AiderSettingsSchema: z.ZodObject<{
 /** Zod schema for AgentSettings */
 export declare const AgentSettingsSchema: z.ZodObject<{
     parallel: z.ZodDefault<z.ZodBoolean>;
-    model: z.ZodDefault<z.ZodEnum<{
-        haiku: "haiku";
-        sonnet: "sonnet";
-        opus: "opus";
-    }>>;
+    model: z.ZodDefault<z.ZodString>;
     isolateParallel: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strip>;
 /**
@@ -373,6 +430,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 +455,8 @@ export declare const RunSettingsSchema: z.ZodObject<{
         }>>;
     }, z.core.$strip>>>;
     effortEscalation: z.ZodDefault<z.ZodBoolean>;
+    autoMerge: z.ZodDefault<z.ZodBoolean>;
+    modelRoles: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>>;
 }, z.core.$strip>;
 /** Zod schema for ScopeThreshold (base — fields required, no defaults) */
 export declare const ScopeThresholdSchema: z.ZodObject<{
@@ -477,6 +537,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,14 +562,12 @@ export declare const SettingsSchema: z.ZodObject<{
             }>>;
         }, z.core.$strip>>>;
         effortEscalation: z.ZodDefault<z.ZodBoolean>;
+        autoMerge: z.ZodDefault<z.ZodBoolean>;
+        modelRoles: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>>;
     }, z.core.$strip>>;
     agents: z.ZodDefault<z.ZodObject<{
         parallel: z.ZodDefault<z.ZodBoolean>;
-        model: z.ZodDefault<z.ZodEnum<{
-            haiku: "haiku";
-            sonnet: "sonnet";
-            opus: "opus";
-        }>>;
+        model: z.ZodDefault<z.ZodString>;
         isolateParallel: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strip>>;
     scopeAssessment: z.ZodDefault<z.ZodObject<{

package/dist/src/lib/settings.js

@@ -25,6 +25,26 @@ export const SETTINGS_VERSION = "1.0";
  * two validation points cannot drift apart on which values are accepted.
  */
 export const EFFORT_LEVELS = ["low", "medium", "high", "xhigh", "max"];
+/**
+ * Map of semantic role names to model strings, used by `run.modelRoles` (#975).
+ *
+ * A value is either:
+ * - a plain string shorthand — desugars to `{ "claude-code": value }` (claude-code driver only)
+ * - an object keyed by driver registry name, for cross-driver mappings
+ *
+ * Role references use a `role:` prefix in phase policy / ladder entries;
+ * bare strings pass through verbatim (AC-3 backward compat).
+ */
+export const ModelRolesSchema = z.record(z.string(), z.union([z.string(), z.record(z.string(), z.string())]));
+/**
+ * Shipped default role map (#975). Family aliases only — no dated model IDs.
+ * Claude-code shorthand form; no opencode/aider entries shipped by default.
+ */
+export const DEFAULT_MODEL_ROLES = {
+    fast: "sonnet",
+    strong: "opus",
+    frontier: "fable",
+};
 // ─── Zod Schemas (AC-1, AC-5) ────────────────────────────────────────────────
 /** Zod schema for RotationSettings */
 export const RotationSettingsSchema = z.object({
@@ -41,7 +61,7 @@ export const AiderSettingsSchema = z.object({
 /** Zod schema for AgentSettings */
 export const AgentSettingsSchema = z.object({
     parallel: z.boolean().default(false),
-    model: z.enum(["haiku", "sonnet", "opus"]).default("haiku"),
+    model: z.string().default("haiku"),
     isolateParallel: z.boolean().default(false),
 });
 /**
@@ -78,6 +98,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 +125,18 @@ 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),
+    /**
+     * Semantic role → model string map (#975). See `ModelRolesSchema` and
+     * `DEFAULT_MODEL_ROLES` for the shipped defaults. Absent from generated
+     * settings — absent key → defaults apply. Do not emit in `generateSettingsJsonc`.
+     */
+    modelRoles: ModelRolesSchema.default(() => ({ ...DEFAULT_MODEL_ROLES })),
 });
 /** Zod schema for ScopeThreshold (base — fields required, no defaults) */
 export const ScopeThresholdSchema = z.object({
@@ -216,6 +249,7 @@ const KNOWN_KEYS = {
         "rotation",
         "defaultBase",
         "mcp",
+        "mcpAllowlist",
         "retry",
         "staleBranchThreshold",
         "resolvedIssueTTL",
@@ -225,6 +259,7 @@ const KNOWN_KEYS = {
         "aider",
         "relay",
         "phases",
+        "modelRoles",
     ]),
     // #914: keyed by real phase name so a typo (`run.phases.exce`) warns
     // instead of silently resolving to nothing. Computed from the registry
@@ -451,6 +486,8 @@ 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
+        modelRoles: DEFAULT_MODEL_ROLES, // #975: shipped defaults; absent key → these
     },
     agents: DEFAULT_AGENT_SETTINGS,
     scopeAssessment: DEFAULT_SCOPE_ASSESSMENT_SETTINGS,
@@ -581,6 +618,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`);
@@ -603,7 +644,7 @@ export function generateSettingsJsonc(settings) {
     lines.push(`  "agents": {`);
     lines.push(`    // Run agents in parallel (faster, higher token usage)`);
     lines.push(`    "parallel": ${JSON.stringify(settings.agents.parallel)},`);
-    lines.push(`    // Default model for sub-agents ("haiku", "sonnet", "opus") — currently inert per anthropics/claude-code#43869`);
+    lines.push(`    // Default model for sub-agents (any alias/ID) — currently inert per anthropics/claude-code#43869`);
     lines.push(`    "model": ${JSON.stringify(settings.agents.model)},`);
     lines.push(`    // Isolate parallel agent groups in separate worktrees`);
     lines.push(`    "isolateParallel": ${JSON.stringify(settings.agents.isolateParallel)}`);
@@ -698,6 +739,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) |
@@ -724,7 +766,7 @@ Generated by \`sequant init\`. See defaults below.
 | Key | Type | Default | Description |
 |-----|------|---------|-------------|
 | \`parallel\` | boolean | \`false\` | Run agents in parallel (faster, higher token usage) |
-| \`model\` | enum | \`"haiku"\` | Default model: \`"haiku"\`, \`"sonnet"\`, or \`"opus"\`. **Currently inert** per [anthropics/claude-code#43869](https://github.com/anthropics/claude-code/issues/43869) — subagents inherit the parent session's model. Kept for forward compatibility. |
+| \`model\` | string | \`"haiku"\` | Default model (any alias or dated ID). **Currently inert** per [anthropics/claude-code#43869](https://github.com/anthropics/claude-code/issues/43869) — subagents inherit the parent session's model. See \`run.modelRoles\` for semantic roles (#975). |
 | \`isolateParallel\` | boolean | \`false\` | Isolate parallel agents in separate worktrees |
 
 ## \`scopeAssessment\` — Scope Assessment Settings

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>;