sequant 2.11.0 → 2.12.0

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

@@ -129,6 +129,50 @@ export declare const ErrorContextSchema: z.ZodObject<{
     isRetryable: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export type ErrorContext = z.infer<typeof ErrorContextSchema>;
+/**
+ * Finite taxonomy for a single gap finding surfaced by `/qa` (#937).
+ *
+ * Replaces the lossy prose-scrape gap channel (`parseListSection` against
+ * `**Issues:**`/`**Gaps**` headers, which misses AC-table NOT_MET rows, §6d
+ * Adversarial Re-Read findings, and §5 Risk Assessment). `evidence` is
+ * required so a finding can't be speculative — see #608's 0%-action-rate
+ * result for open-ended "what might we be missing" findings.
+ */
+export declare const GapCategorySchema: z.ZodEnum<{
+    requirement_gap: "requirement_gap";
+    dependency_gap: "dependency_gap";
+    test_gap: "test_gap";
+    repository_gap: "repository_gap";
+    risk_gap: "risk_gap";
+    execution_gap: "execution_gap";
+}>;
+export type GapCategory = z.infer<typeof GapCategorySchema>;
+export declare const GapActionSchema: z.ZodEnum<{
+    fix_now: "fix_now";
+    document: "document";
+    pause_for_human: "pause_for_human";
+}>;
+export type GapAction = z.infer<typeof GapActionSchema>;
+export declare const GapFindingSchema: z.ZodObject<{
+    category: z.ZodEnum<{
+        requirement_gap: "requirement_gap";
+        dependency_gap: "dependency_gap";
+        test_gap: "test_gap";
+        repository_gap: "repository_gap";
+        risk_gap: "risk_gap";
+        execution_gap: "execution_gap";
+    }>;
+    evidence: z.ZodString;
+    description: z.ZodString;
+    recommendedAction: z.ZodEnum<{
+        fix_now: "fix_now";
+        document: "document";
+        pause_for_human: "pause_for_human";
+    }>;
+    affectedAcs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    nonGoal: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type GapFinding = z.infer<typeof GapFindingSchema>;
 /**
  * Condensed QA verdict summary for structured log output (#434).
  *
@@ -141,6 +185,25 @@ export declare const QaSummarySchema: z.ZodObject<{
     acTotal: z.ZodNumber;
     gaps: z.ZodArray<z.ZodString>;
     suggestions: z.ZodArray<z.ZodString>;
+    findings: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        category: z.ZodEnum<{
+            requirement_gap: "requirement_gap";
+            dependency_gap: "dependency_gap";
+            test_gap: "test_gap";
+            repository_gap: "repository_gap";
+            risk_gap: "risk_gap";
+            execution_gap: "execution_gap";
+        }>;
+        evidence: z.ZodString;
+        description: z.ZodString;
+        recommendedAction: z.ZodEnum<{
+            fix_now: "fix_now";
+            document: "document";
+            pause_for_human: "pause_for_human";
+        }>;
+        affectedAcs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        nonGoal: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>>;
 }, z.core.$strip>;
 export type QaSummary = z.infer<typeof QaSummarySchema>;
 /**
@@ -175,6 +238,25 @@ export declare const PhaseLogSchema: z.ZodObject<{
         acTotal: z.ZodNumber;
         gaps: z.ZodArray<z.ZodString>;
         suggestions: z.ZodArray<z.ZodString>;
+        findings: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            category: z.ZodEnum<{
+                requirement_gap: "requirement_gap";
+                dependency_gap: "dependency_gap";
+                test_gap: "test_gap";
+                repository_gap: "repository_gap";
+                risk_gap: "risk_gap";
+                execution_gap: "execution_gap";
+            }>;
+            evidence: z.ZodString;
+            description: z.ZodString;
+            recommendedAction: z.ZodEnum<{
+                fix_now: "fix_now";
+                document: "document";
+                pause_for_human: "pause_for_human";
+            }>;
+            affectedAcs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            nonGoal: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>>;
     }, z.core.$strip>>;
     commitHash: z.ZodOptional<z.ZodString>;
     fileDiffStats: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -255,6 +337,25 @@ export declare const IssueLogSchema: z.ZodObject<{
             acTotal: z.ZodNumber;
             gaps: z.ZodArray<z.ZodString>;
             suggestions: z.ZodArray<z.ZodString>;
+            findings: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                category: z.ZodEnum<{
+                    requirement_gap: "requirement_gap";
+                    dependency_gap: "dependency_gap";
+                    test_gap: "test_gap";
+                    repository_gap: "repository_gap";
+                    risk_gap: "risk_gap";
+                    execution_gap: "execution_gap";
+                }>;
+                evidence: z.ZodString;
+                description: z.ZodString;
+                recommendedAction: z.ZodEnum<{
+                    fix_now: "fix_now";
+                    document: "document";
+                    pause_for_human: "pause_for_human";
+                }>;
+                affectedAcs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                nonGoal: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$strip>>>;
         }, z.core.$strip>>;
         commitHash: z.ZodOptional<z.ZodString>;
         fileDiffStats: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -390,6 +491,25 @@ export declare const RunLogSchema: z.ZodObject<{
                 acTotal: z.ZodNumber;
                 gaps: z.ZodArray<z.ZodString>;
                 suggestions: z.ZodArray<z.ZodString>;
+                findings: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    category: z.ZodEnum<{
+                        requirement_gap: "requirement_gap";
+                        dependency_gap: "dependency_gap";
+                        test_gap: "test_gap";
+                        repository_gap: "repository_gap";
+                        risk_gap: "risk_gap";
+                        execution_gap: "execution_gap";
+                    }>;
+                    evidence: z.ZodString;
+                    description: z.ZodString;
+                    recommendedAction: z.ZodEnum<{
+                        fix_now: "fix_now";
+                        document: "document";
+                        pause_for_human: "pause_for_human";
+                    }>;
+                    affectedAcs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                    nonGoal: z.ZodOptional<z.ZodBoolean>;
+                }, z.core.$strip>>>;
             }, z.core.$strip>>;
             commitHash: z.ZodOptional<z.ZodString>;
             fileDiffStats: z.ZodOptional<z.ZodArray<z.ZodObject<{

package/dist/src/lib/workflow/run-log-schema.js

@@ -129,6 +129,39 @@ export const ErrorContextSchema = z.object({
     /** Whether this error type is retryable (AC-9) */
     isRetryable: z.boolean().optional(),
 });
+/**
+ * Finite taxonomy for a single gap finding surfaced by `/qa` (#937).
+ *
+ * Replaces the lossy prose-scrape gap channel (`parseListSection` against
+ * `**Issues:**`/`**Gaps**` headers, which misses AC-table NOT_MET rows, §6d
+ * Adversarial Re-Read findings, and §5 Risk Assessment). `evidence` is
+ * required so a finding can't be speculative — see #608's 0%-action-rate
+ * result for open-ended "what might we be missing" findings.
+ */
+export const GapCategorySchema = z.enum([
+    "requirement_gap",
+    "dependency_gap",
+    "test_gap",
+    "repository_gap",
+    "risk_gap",
+    "execution_gap",
+]);
+export const GapActionSchema = z.enum([
+    "fix_now",
+    "document",
+    "pause_for_human",
+]);
+export const GapFindingSchema = z.object({
+    category: GapCategorySchema,
+    /** Concrete observation grounding the finding — never speculation. */
+    evidence: z.string().min(1),
+    description: z.string().min(1),
+    recommendedAction: GapActionSchema,
+    /** ACs this finding relates to, e.g. ["AC-3"]. */
+    affectedAcs: z.array(z.string()).optional(),
+    /** True when the finding overlaps one of the issue's Non-Goals. */
+    nonGoal: z.boolean().optional(),
+});
 /**
  * Condensed QA verdict summary for structured log output (#434).
  *
@@ -145,6 +178,13 @@ export const QaSummarySchema = z.object({
     gaps: z.array(z.string()),
     /** List of improvement suggestions from QA */
     suggestions: z.array(z.string()),
+    /**
+     * Structured gap findings parsed from the `SEQUANT_QA_GAPS` marker (#937).
+     * Present only when the marker was found and validated; `gaps` above
+     * always carries the union of marker + prose descriptions (dedupe'd) so
+     * marker-unaware consumers never regress.
+     */
+    findings: z.array(GapFindingSchema).optional(),
 });
 /**
  * Log entry for a single phase execution

package/dist/src/lib/workflow/state-schema.d.ts

@@ -149,6 +149,7 @@ export declare const AcceptanceCriterionSchema: z.ZodObject<{
     }>;
     verifiedAt: z.ZodOptional<z.ZodString>;
     notes: z.ZodOptional<z.ZodString>;
+    evidence: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type AcceptanceCriterion = z.infer<typeof AcceptanceCriterionSchema>;
 /**
@@ -172,6 +173,7 @@ export declare const AcceptanceCriteriaSchema: z.ZodObject<{
         }>;
         verifiedAt: z.ZodOptional<z.ZodString>;
         notes: z.ZodOptional<z.ZodString>;
+        evidence: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
     extractedAt: z.ZodString;
     summary: z.ZodObject<{
@@ -281,6 +283,7 @@ export declare const IssueStateSchema: z.ZodObject<{
             }>;
             verifiedAt: z.ZodOptional<z.ZodString>;
             notes: z.ZodOptional<z.ZodString>;
+            evidence: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
         extractedAt: z.ZodString;
         summary: z.ZodObject<{
@@ -430,6 +433,7 @@ export declare const WorkflowStateSchema: z.ZodObject<{
                 }>;
                 verifiedAt: z.ZodOptional<z.ZodString>;
                 notes: z.ZodOptional<z.ZodString>;
+                evidence: z.ZodOptional<z.ZodString>;
             }, z.core.$strip>>;
             extractedAt: z.ZodString;
             summary: z.ZodObject<{
@@ -538,7 +542,7 @@ export declare function createPhaseState(status?: PhaseStatus): PhaseState;
 /**
  * Create acceptance criterion
  */
-export declare function createAcceptanceCriterion(id: string, description: string, verificationMethod?: ACVerificationMethod): AcceptanceCriterion;
+export declare function createAcceptanceCriterion(id: string, description: string, verificationMethod?: ACVerificationMethod, evidence?: string): AcceptanceCriterion;
 /**
  * Create acceptance criteria tracking structure
  */

package/dist/src/lib/workflow/state-schema.js

@@ -149,6 +149,12 @@ export const AcceptanceCriterionSchema = z.object({
     verifiedAt: z.string().datetime().optional(),
     /** Additional notes about verification */
     notes: z.string().optional(),
+    /**
+     * Explicit `Evidence:` clause declared on the AC line (#938). When present,
+     * this is what verificationMethod was resolved from instead of keyword
+     * inference — see `resolveVerificationMethod` in ac-parser.ts.
+     */
+    evidence: z.string().optional(),
 });
 /**
  * Acceptance criteria tracking for an issue
@@ -369,12 +375,13 @@ export function createPhaseState(status = "pending") {
 /**
  * Create acceptance criterion
  */
-export function createAcceptanceCriterion(id, description, verificationMethod = "manual") {
+export function createAcceptanceCriterion(id, description, verificationMethod = "manual", evidence) {
     return {
         id,
         description,
         verificationMethod,
         status: "pending",
+        ...(evidence !== undefined ? { evidence } : {}),
     };
 }
 /**

package/dist/src/lib/workflow/types.d.ts

@@ -83,6 +83,15 @@ export interface ExecutionConfig {
     dryRun: boolean;
     /** Enable MCP servers in headless mode (true by default, false if --no-mcp flag used) */
     mcp: boolean;
+    /**
+     * Claude Desktop MCP server names explicitly opted in via
+     * `settings.run.mcpAllowlist` (#936). Both `ExecutionConfig` producers
+     * (`buildExecutionConfig`, `ready-gate.ts`'s `buildPhaseConfig`) read
+     * this from settings the same way, so it cannot drift between them the
+     * way #833's `phaseTimeout` once did. `phase-executor.ts` forwards it
+     * verbatim onto `AgentExecutionConfig.mcpAllowlist`.
+     */
+    mcpAllowlist?: string[];
     /**
      * Enable automatic retry with MCP fallback.
      * When true (default), failed phases are retried with MCP disabled.
@@ -705,4 +714,9 @@ export interface IssueExecutionContext {
      * around verbose Claude streaming.
      */
     phasePauseHandle?: PhasePauseHandle;
+    /**
+     * @internal Test seam for the #964 qa-verdict comment post. Defaults to a
+     * real `GitHubProvider().postComment` when unset.
+     */
+    postComment?: (issueNumber: number, body: string) => Promise<void>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sequant",
-  "version": "2.11.0",
+  "version": "2.12.0",
   "description": "AI coding agent orchestrator — resolve GitHub issues end-to-end with isolated git worktrees, quality gates, and an MCP server. Works with Claude Code or Aider.",
   "type": "module",
   "bin": {
@@ -94,7 +94,7 @@
     "@anthropic-ai/claude-agent-sdk": "^0.3.142",
     "@hono/node-server": "^2.0.0",
     "boxen": "^8.0.1",
-    "chalk": "^5.3.0",
+    "chalk": "^6.0.0",
     "chokidar": "^5.0.0",
     "cli-table3": "^0.6.5",
     "commander": "^14.0.3",

package/templates/hooks/pre-tool.sh

@@ -39,7 +39,55 @@ else
     HOOK_CWD=$(echo "$INPUT_JSON" | grep -oE '"cwd"\s*:\s*"[^"]+"' | head -1 | cut -d'"' -f4)
     # For Bash tool, extract command from tool_input; for others, extract the whole object
     if [[ "$TOOL_NAME" == "Bash" ]]; then
-        TOOL_INPUT=$(echo "$INPUT_JSON" | grep -oE '"command"\s*:\s*"[^"]+"' | head -1 | cut -d'"' -f4)
+        # Escape-aware extraction (#963 gap B): the naive `grep -oE '"[^"]+"'`
+        # form (still used for the simpler fields above, where an embedded
+        # `\"` is implausible) stops at the FIRST escaped quote inside the
+        # JSON string, truncating any command containing one — e.g.
+        # `git commit -m "msg with \"quotes\""` would be cut down to just
+        # `git commit -m ` before it ever reaches the guards below.
+        #
+        # sed's `(([^"\\]|\\.)*)` captures the full escaped run — any run of
+        # non-quote/non-backslash chars, or a backslash paired with whatever
+        # follows it — up to the closing unescaped `"`. `JSON.stringify`
+        # guarantees the whole payload is one physical line, so a single
+        # sed pass is enough (no multi-line `-z` needed, which BSD sed lacks
+        # anyway).
+        #
+        # The captured text still carries JSON string escapes literally
+        # (`\"`, `\\`, `\n`, `\t`, ...); the awk pass resolves them in ONE
+        # left-to-right scan, consuming two characters per recognized
+        # escape. That ordering is what a chain of separate sed/tr
+        # substitutions cannot get right without a placeholder: a literal
+        # `\\n` in the original command is an escaped backslash (`\\`)
+        # immediately followed by a literal `n`, and must stay a backslash
+        # plus 'n' — not become an escaped-newline (`\n`) if the two escapes
+        # were resolved out of order. Scanning once and advancing past both
+        # characters of whichever escape is recognized sidesteps that
+        # ambiguity entirely.
+        TOOL_INPUT=$(printf '%s' "$INPUT_JSON" \
+            | sed -E -n 's/.*"command"[[:space:]]*:[[:space:]]*"(([^"\\]|\\.)*)".*/\1/p' \
+            | head -1 \
+            | awk '
+                {
+                    s = $0; out = ""; n = length(s)
+                    for (i = 1; i <= n; i++) {
+                        c = substr(s, i, 1)
+                        if (c == "\\" && i < n) {
+                            nc = substr(s, i + 1, 1)
+                            if (nc == "\"") { out = out "\""; i++ }
+                            else if (nc == "\\") { out = out "\\"; i++ }
+                            else if (nc == "n") { out = out "\n"; i++ }
+                            else if (nc == "t") { out = out "\t"; i++ }
+                            else if (nc == "r") { out = out "\r"; i++ }
+                            else if (nc == "/") { out = out "/"; i++ }
+                            else { out = out c }
+                        } else {
+                            out = out c
+                        }
+                    }
+                    print out
+                }
+            ')
     else
         TOOL_INPUT=$(echo "$INPUT_JSON" | grep -oE '"tool_input"\s*:\s*\{[^}]+\}' | head -1)
     fi
@@ -258,6 +306,43 @@ seg_match() {
     [[ -n "$SEGMENTS" ]] && grep -qE "$1" <<< "$SEGMENTS"
 }
 
+# resolve_cd_target <tool_input> — print the target directory of the LAST
+# `cd <path>` line in a (possibly multi-line) Bash command, if and only if
+# the path is a static literal (quoted or unquoted) that resolves to an
+# existing directory. Scans the raw command, not $SEGMENTS — emit_segments
+# drops double-quoted regions, so `cd "$WT"` would vanish there before this
+# ever saw it. Prints nothing when there is no `cd` line, the target is
+# dynamic (contains `$` or a backtick), or the path doesn't exist — callers
+# must treat empty output as "fail open", never as license to guess a
+# directory (#963).
+resolve_cd_target() {
+    local input="$1" line target
+    line=$(printf '%s\n' "$input" | grep -E '^[[:space:]]*cd[[:space:]]+' | tail -1)
+    [[ -z "$line" ]] && return 0
+
+    target=$(printf '%s' "$line" | sed -E 's/^[[:space:]]*cd[[:space:]]+//; s/[[:space:]]*[;&|].*$//; s/[[:space:]]+$//')
+
+    # Strip one layer of surrounding matching quotes.
+    case "$target" in
+        \"*\") target="${target#\"}"; target="${target%\"}" ;;
+        \'*\') target="${target#\'}"; target="${target%\'}" ;;
+    esac
+
+    # Fail open on anything dynamic — resolving shell expansions means
+    # reimplementing the shell, which is disproportionate; `git commit`
+    # itself already rejects a genuinely empty commit. A backslash is
+    # rejected too: it can escape a following `$`/`` ` `` into a form this
+    # literal-string check would otherwise miss, and a backslash also carries
+    # its own shell meaning (line continuation, escaped chars) that this
+    # function does not attempt to resolve — failing open is the safe
+    # direction either way (#963).
+    case "$target" in
+        *'$'*|*'`'*|*'\'*) return 0 ;;
+    esac
+
+    [[ -n "$target" && -d "$target" ]] && printf '%s' "$target"
+}
+
 # Path of the session->issue binding the checkout guard maintains (#906).
 # $1 = repo toplevel, $2 = session id. The id is opaque, so squash everything
 # outside a filename-safe set — it must not be able to escape the directory.
@@ -552,11 +637,10 @@ if [[ -z "${SEQUANT_ORCHESTRATOR:-}" ]] \
     # `.cwd` is part of Claude Code's PreToolUse envelope (verified against a
     # live payload alongside `session_id`), with $PWD as the fallback.
     _CO_CWD="${HOOK_CWD:-$PWD}"
-    # Honor a leading `cd <dir>` the same way the commit guard below does.
-    if echo "$TOOL_INPUT" | grep -qE '^cd [^;&|]+'; then
-        _CO_CD=$(echo "$TOOL_INPUT" | grep -oE '^cd [^;&|]+' | head -1 | sed 's/^cd //' | sed 's/[[:space:]]*$//')
-        [[ -n "$_CO_CD" && -d "$_CO_CD" ]] && _CO_CWD="$_CO_CD"
-    fi
+    # Honor a `cd <dir>` the same way the commit guard below does — including
+    # multi-line commands and quoted/dynamic targets (#963).
+    _CO_CD=$(resolve_cd_target "$TOOL_INPUT")
+    [[ -n "$_CO_CD" ]] && _CO_CWD="$_CO_CD"
 
     # A linked worktree's toplevel has `.git` as a FILE; the main checkout has
     # it as a directory.
@@ -782,18 +866,25 @@ fi
 # Skips for --amend since amending doesn't require new changes
 if [[ "$TOOL_NAME" == "Bash" ]] && seg_match 'git commit'; then
     if ! echo "$TOOL_INPUT" | grep -qE -- '--amend|--allow-empty'; then
-        # Extract target directory from cd command if present (for worktree commits)
-        # Handles: "cd /path && git commit" or "cd /path; git commit"
-        TARGET_DIR=""
-        if echo "$TOOL_INPUT" | grep -qE '^cd [^;&|]+'; then
-            TARGET_DIR=$(echo "$TOOL_INPUT" | grep -oE '^cd [^;&|]+' | head -1 | sed 's/^cd //' | tr -d ' ')
-        fi
-
-        # Check for changes in the target directory (or current if no cd)
-        if [[ -n "$TARGET_DIR" && -d "$TARGET_DIR" ]]; then
-            CHANGES=$(cd "$TARGET_DIR" && git status --porcelain 2>/dev/null | wc -l | tr -d ' ')
+        # Resolve where to check for changes: the last resolvable `cd`
+        # target if the command has one (multi-line commands included —
+        # #963), else the command's own cwd from the hook payload (never
+        # this hook process's own cwd, which need not match).
+        TARGET_DIR=$(resolve_cd_target "$TOOL_INPUT")
+        HAS_CD_LINE=false
+        echo "$TOOL_INPUT" | grep -qE '^[[:space:]]*cd[[:space:]]+' && HAS_CD_LINE=true
+
+        if [[ -n "$TARGET_DIR" ]]; then
+            CHANGES=$(git -C "$TARGET_DIR" status --porcelain 2>/dev/null | wc -l | tr -d ' ')
+        elif [[ "$HAS_CD_LINE" == true ]]; then
+            # A `cd` line is present but its target is dynamic (a shell
+            # variable/command substitution) or doesn't exist as a
+            # directory — fail open rather than check the wrong
+            # directory. `git commit` itself already rejects a genuinely
+            # empty commit, so this costs one harmless git error (#963).
+            CHANGES=1
         else
-            CHANGES=$(git status --porcelain 2>/dev/null | wc -l | tr -d ' ')
+            CHANGES=$(git -C "${HOOK_CWD:-$PWD}" status --porcelain 2>/dev/null | wc -l | tr -d ' ')
         fi
 
         if [[ "$CHANGES" -eq 0 ]]; then

package/templates/skills/exec/SKILL.md

@@ -1955,7 +1955,7 @@ The goal is to satisfy AC with the smallest, safest change possible.
 ### 6. Progress Summary and Draft Issue Update
 
 **If orchestrated (SEQUANT_ORCHESTRATOR is set):**
-- Skip posting progress comments to GitHub (orchestrator handles summary)
+- Skip posting progress comments to GitHub — no per-phase comment is posted under `sequant run`; progress surfaces through the run summary and the PR body (#964)
 - Still provide AC coverage summary in output for orchestrator to capture
 - Let orchestrator handle final GitHub update
 

package/templates/skills/fullsolve/SKILL.md

@@ -23,7 +23,6 @@ allowed-tools:
   - Bash(gh issue edit:*)
   - Bash(gh pr create:*)
   - Bash(gh pr list:*)
-  - Bash(gh pr merge:*)
   - Bash(npm test:*)
   - Bash(npm run build:*)
   - Bash(git diff:*)
@@ -52,22 +51,28 @@ When invoked as `/fullsolve <issue-number>`, execute the complete issue resoluti
 
 ## CRITICAL: Auto-Progression Between Phases
 
-**DO NOT wait for user confirmation between phases.** This is an autonomous workflow.
+**DO NOT wait for user confirmation between phases.** This is an autonomous workflow — through PR creation.
 
 After each phase completes successfully, **immediately proceed** to the next phase:
 1. `/spec` completes → **immediately** invoke `/exec`
 2. `/exec` completes → **immediately** invoke `/test` (if UI) or `/qa`
 3. `/test` completes → **immediately** invoke `/qa`
-4. `/qa` completes → **immediately** create PR
+4. `/qa` completes → **immediately** create the PR and post the final summary
 
-**The user invoked `/fullsolve` expecting end-to-end automation.** Only stop for:
+<!-- BEGIN: merge-gate (#958) -->
+**The workflow's terminal state is PR created + final summary posted — not merged.** Merging (§5.3), post-merge verification (§5.4), and the auto-merge-path lock release (§5.5) run **only** when `--auto-merge` is passed, `run.autoMerge` is `true` in `.sequant/settings.json`, or the user has explicitly instructed a merge in this conversation (invoking `/fullsolve` alone does not count). Without one of those, `/fullsolve` stops after the final summary — the PR is left open for human review. See "Merge Gate" below for how this is resolved, and §5.3 for the gate itself.
+
+**The user invoked `/fullsolve` expecting end-to-end automation up to a mergeable PR.** Only stop for:
 - Unrecoverable errors (after retry attempts exhausted)
-- Final summary after PR creation
+- Final summary after PR creation — **this is the workflow's terminal state**, not a pause
 - Explicit user interruption
+<!-- END: merge-gate (#958) -->
 
 ```
 WRONG: "Spec complete. Ready for exec phase." [waits]
 RIGHT: "Spec complete. Proceeding to exec..." [invokes /exec immediately]
+WRONG (no --auto-merge): [creates PR, immediately runs `gh pr merge`]
+RIGHT (no --auto-merge): [creates PR, posts final summary, stops]
 ```
 
 ## Workflow Overview
@@ -125,6 +130,7 @@ RIGHT: "Spec complete. Proceeding to exec..." [invokes /exec immediately]
 /fullsolve 218 --max-iterations 5 # Override max fix iterations
 /fullsolve 218 --parallel         # Force parallel agent execution (faster, higher token usage)
 /fullsolve 218 --sequential       # Force sequential agent execution (slower, lower token usage)
+/fullsolve 218 --auto-merge       # Merge the PR automatically once QA passes (default: off)
 ```
 
 ## Agent Execution Mode
@@ -151,6 +157,30 @@ When spawning sub-agents for quality checks, determine the execution mode:
 
 **Pass execution mode to child skills:** When invoking `/qa` or other skills that spawn agents, pass the `--parallel` or `--sequential` flag to maintain consistency.
 
+## Merge Gate (#958)
+
+Determine whether Phase 5.3–5.5's merge workflow runs at all. This mirrors the Agent Execution Mode resolution above — flag first, then settings, defaulting closed.
+
+1. **Check for CLI flag override:**
+   - `--auto-merge` → run the merge workflow (§5.3) after the final summary
+   - No flag → do not merge automatically; fall through to step 2
+
+2. **If no flag, read project settings:**
+   Use the Read tool to check project settings:
+   ```
+   Read(file_path=".sequant/settings.json")
+   # Parse JSON and extract run.autoMerge (default: false)
+   ```
+
+3. **Default:** off. `/fullsolve` ends at PR creation + final summary — this
+   preserves the human merge gate recorded in #817–#819 (`sequant ready`
+   drives an issue to merge-*readiness*; a human runs `sequant merge` to
+   actually merge it).
+
+**Explicit user instruction overrides the gate independent of the flag or setting.** If the user has told you in this conversation to merge once ready (not merely "run `/fullsolve`"), treat that as satisfying the gate for this run.
+
+**If the gate does not fire:** skip §5.3 and §5.4 entirely. Release the concurrency locks immediately after §5.2 (see §5.5) and stop — do not attempt `gh pr merge` under any circumstance without one of the three conditions above.
+
 ## Orchestration Context
 
 This skill acts as an **orchestrator** and sets environment variables for child skills to optimize their behavior:
@@ -306,7 +336,7 @@ npx sequant locks checkout acquire \
 
 Release it alongside the per-issue lock: `npx sequant locks checkout release --issue=<issue-number> || true`. **`--issue` is mandatory** (#906) — it is what proves you are the holder. `--skip-pid-check` means the acquiring shell's PID is already dead, so PID identity is unavailable and a release without `--issue` is refused, not merely ineffective. Stale recovery is therefore age-based only for this lock: the 6h `SEQUANT_SKILL_LOCK_TTL_MS` and the 24h `SEQUANT_MAX_LOCK_AGE_MS` ceiling, *not* same-host dead-PID recovery, which `--skip-pid-check` disables by definition. An abandoned holder still cannot wedge the checkout permanently.
 
-**Release contract:** Phase 5.5 releases both locks on the happy path. On ANY branch that **exits the workflow without reaching Phase 5** — spec failure, exec iterations exhausted, unrecoverable error — you MUST run `npx sequant locks release <issue-number> || true` and `npx sequant locks checkout release --issue=<issue-number> || true` **before** printing the halt message. The explicit release calls below cover the known branches; if you add a new early-exit path, add a release call there too.
+**Release contract (#958):** the happy path releases both locks **right after §5.2's final summary** — that is the workflow's default terminal state, since §5.3–5.4 do not run without the Merge Gate firing. Only when the Merge Gate *does* fire does release move to §5.5, after merge (§5.3) and post-merge verification (§5.4) complete. On ANY branch that **exits the workflow without reaching Phase 5** — spec failure, exec iterations exhausted, unrecoverable error — you MUST run `npx sequant locks release <issue-number> || true` and `npx sequant locks checkout release --issue=<issue-number> || true` **before** printing the halt message. The explicit release calls below cover the known branches; if you add a new early-exit path, add a release call there too.
 
 **Do NOT release at a branch that continues to Phase 5.** QA-loop exhaustion and the stagnation halt both fall through to PR creation, which still runs git in this tree — releasing there would leave Phase 5 unprotected.
 
@@ -763,9 +793,17 @@ Post completion comment to issue with:
 - PR link
 - Quality metrics
 
-### 5.3 Merge Workflow (Correct Order)
+### 5.3 Merge Workflow (Opt-In Only) (#958)
 
-**IMPORTANT:** Merge the PR first, then clean up the worktree.
+**STOP — do not run this section unless the Merge Gate above fired.** That
+means one of: `--auto-merge` was passed on this `/fullsolve` invocation,
+`run.autoMerge` is `true` in `.sequant/settings.json`, or the user
+explicitly instructed a merge in this conversation. If none of those hold,
+**do not run `gh pr merge`.** Stop after §5.2's final summary instead — the
+PR stays open, awaiting human review. That is the default terminal state,
+not a fallback.
+
+**IMPORTANT (once the gate above has fired):** Merge the PR first, then clean up the worktree.
 
 ```bash
 # 1. Merge PR (without --delete-branch; cleanup happens after success)
@@ -783,6 +821,8 @@ gh pr merge <N> --squash
 
 ### 5.4 Post-Merge Verification
 
+**Skip this section if §5.3 did not run.** Nothing to verify post-merge when there was no merge.
+
 **Recommended:** After merge, verify the build and CLI still work:
 
 ```bash
@@ -800,7 +840,14 @@ If any command fails, fix immediately on main before continuing. This catches is
 
 ### 5.5 Release Concurrency Locks (#625, #901)
 
-After the PR is created (or earlier if the workflow exits gracefully), release both locks so other sessions can claim them:
+**Default path (Merge Gate did not fire):** release runs immediately after
+§5.2's final summary — that is the happy path, since §5.3–5.4 never execute.
+Run the release calls below there, not here.
+
+**Auto-merge path (Merge Gate fired):** release runs here, after §5.3
+(merge) and §5.4 (post-merge verification) complete.
+
+Either way, release both locks so other sessions can claim them:
 
 ```bash
 npx sequant locks release <issue-number> || true
@@ -949,6 +996,7 @@ Do **not** run it on the two branches below that continue to Phase 5 — "test l
 | MAX_QA_ITERATIONS | 2 | Max fix loops for QA phase |
 | SKIP_TEST | false | Skip testing phase |
 | AUTO_PR | true | Create PR automatically |
+| AUTO_MERGE | false | Merge the PR automatically once QA passes (#958) |
 
 ## Smart Tests Integration
 
@@ -993,6 +1041,11 @@ npx tsx scripts/dev/analyze-hook-logs.ts --tests
 /fullsolve 218 --max-iterations 5
 ```
 
+**End-to-end including merge:**
+```
+/fullsolve 218 --auto-merge
+```
+
 ## Batch Processing
 
 For multiple issues, run `/fullsolve` on each sequentially: