sequant 2.11.0 → 2.13.0

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/memory/constitution.md

@@ -1,64 +1,131 @@
-# {{PROJECT_NAME}} Constitution
+# {{PROJECT_NAME}} Agent Contract
 
-This document defines the core principles and patterns for AI-assisted development in this project.
+This document is the enforceable contract surface for AI-assisted development in this project. Every section either machine-checked or referenced by a named skill at a named decision point. Values with no consumer are not present.
 
-## Core Principles
+---
 
-1. **Quality First** - Never sacrifice code quality for speed
-2. **Test Everything** - All features must have appropriate test coverage
-3. **Document Decisions** - Important decisions should be captured in issue comments
-4. **Incremental Progress** - Break large tasks into small, reviewable chunks
-5. **Respect Existing Patterns** - Follow established project conventions
+## 1. Definition of Done
 
-## Workflow Phases
+Every PR must pass all gates below before merge. Verified by `/qa` §7 — the table is generated from that section and cannot drift from it (`lint:constitution-dod` fails CI on divergence).
 
-### Phase 1: Planning (`/spec`)
-- Understand requirements and acceptance criteria
-- Identify potential risks and dependencies
-- Draft implementation plan for approval
+**These are project-wide gates. Do not restate them as issue-level ACs.**
 
-### Phase 2: Implementation (`/exec`)
-- Work in feature worktree
-- Follow established patterns
-- Keep commits atomic and well-described
+<!-- BEGIN:DOD-GATES -->
+| Gate | Trigger | Verdict impact |
+|------|---------|----------------|
+| All ACs MET | any `NOT_MET` or `PARTIALLY_MET` | `AC_NOT_MET` — blocks merge |
+| Detection patterns (§6c) | `Failed` | `AC_NOT_MET` — blocks merge |
+| Behavior-rule check (§6e) | `Survivors Found` | `AC_NOT_MET` — blocks merge |
+| Trust boundary (§6f) | `Injection Acted On` | `AC_NOT_MET` — blocks merge |
+| CLI registration (§2h) | `Failed` | `AC_NOT_MET` — blocks merge |
+| Mutation verification (§6i) | `Failed` | `AC_NOT_MET` — blocks merge |
+| Adversarial re-read (§6d) | `Severe Gap` | `AC_NOT_MET` — blocks merge |
+| Skill verification (§6a) | `Failed` | `AC_MET_BUT_NOT_A_PLUS` — cannot be A+ |
+| Script execution evidence | `Incomplete` | `AC_MET_BUT_NOT_A_PLUS` — cannot be A+ |
+| Declared evidence (§6h) | `Incomplete` | `AC_MET_BUT_NOT_A_PLUS` — cannot be A+ |
+| Mutation verification (§6i) | `Missing` | `AC_MET_BUT_NOT_A_PLUS` — cannot be A+ |
+| Script verification (§11) | `Not Verified` | `AC_MET_BUT_NOT_A_PLUS` — cannot be A+ |
+| CHANGELOG entry (§10a) | both conditions true | `AC_MET_BUT_NOT_A_PLUS` — cannot be A+ |
+| Quality plan (Phase 0b) | both conditions true | `AC_MET_BUT_NOT_A_PLUS` — cannot be A+ |
+| Browser test | condition true | `AC_MET_BUT_NOT_A_PLUS` — cannot be A+ |
+| Pending verifications | count `> 0` | `NEEDS_VERIFICATION` — holds for external verification |
+| Quality plan (Phase 0b) | `Partial` | `AC_MET_BUT_NOT_A_PLUS` — cannot be A+ |
+| Smoke tests (§6b) | `Partial` | `AC_MET_BUT_NOT_A_PLUS` — cannot be A+ |
+| Detection patterns (§6c) | `Insufficient Samples` | `AC_MET_BUT_NOT_A_PLUS` — cannot be A+ |
+| Detection patterns (§6c) | `Skipped` | `AC_MET_BUT_NOT_A_PLUS` — cannot be A+ |
+| Adversarial re-read (§6d) | `Gaps Found` | `AC_MET_BUT_NOT_A_PLUS` — cannot be A+ |
+| Improvement suggestions | list non-empty | `AC_MET_BUT_NOT_A_PLUS` — cannot be A+ |
+<!-- END:DOD-GATES -->
 
-### Phase 3: Quality (`/qa`)
-- Review against acceptance criteria
-- Run all quality checks
-- Address feedback before merge
+---
 
-## Code Standards
+## 2. AC Authoring Standard
 
-### Naming Conventions
-- Use descriptive variable and function names
-- Follow language-specific conventions (camelCase, snake_case, etc.)
+Referenced by `/spec`'s AC Quality Check step when flagging lint warnings.
 
-### Error Handling
-- Handle errors gracefully
-- Log meaningful error messages
-- Don't swallow exceptions silently
+### Format rules
 
-### Testing
-- Write tests for new features
-- Update tests when modifying existing code
-- Test edge cases and error paths
+**Write each AC on a single line.** The parser is line-anchored; an AC that wraps to a second line is silently truncated at the first newline, producing a partial description with no `Evidence:` or `Risk:` clause. This is the most common AC-hygiene defect in this repo.
 
-## Commands Available
+**Required fields for testable ACs:**
 
-| Command | Purpose |
-|---------|---------|
-| `/spec` | Plan implementation for an issue |
-| `/exec` | Implement a planned feature |
-| `/test` | Run browser-based UI tests |
-| `/qa` | Quality review before merge |
-| `/loop` | Fix iteration when tests fail |
-| `/docs` | Generate feature documentation |
+| Field | Purpose | Required when |
+|-------|---------|---------------|
+| `Evidence:` | Names the artifact that proves the AC was met | AC is verifiable by code review or test |
+| `Risk:` | Names the failure mode if this AC is wrong | AC has a non-obvious failure mode |
+| `Human decision` | Flags the AC as requiring human judgment | AC cannot be verified mechanically |
 
-## Stack-Specific Notes
+**Non-Goals section:** Every issue must have a `## Non-Goals` section. Scope without a boundary is unbounded scope. The Non-Goals section is where you declare what the issue explicitly does not do.
+
+### Examples
+
+**Bad** (three violations on one AC):
+```
+- [ ] **AC-3:** The feature should work correctly and handle errors
+  gracefully with good test coverage.
+```
+Problems: wraps to second line (parser truncates), "work correctly" is not measurable, no `Evidence:` clause.
+
+**Good** (single line, measurable, evidence declared):
+```
+- [ ] **AC-3:** `/spec`'s AC Quality Check output references the constitution AC standard. Evidence: scoped gate test on the spec skill's reference string, mutation-verified.
+```
+
+---
+
+## 3. Boundaries
+
+Every rule below names its enforcing mechanism. Rules without a named enforcer are not in this section.
+
+| Rule | Enforcing mechanism |
+|------|---------------------|
+| No force-push or amend on pushed branches | `templates/hooks/pre-tool.sh` (pre-tool hook, `HOOK_BLOCKED: Force push`) |
+| No edits outside the issue worktree | `templates/hooks/pre-tool.sh` (worktree-only editing guard) |
+| Gate tests must be mutation-verified | `/qa` §6i + `SEQUANT_MUTATION` marker in PR body (#939); `Missing` caps at `AC_MET_BUT_NOT_A_PLUS`, `Failed` floors at `AC_NOT_MET` |
+| All §1 Definition of Done gates | `/qa` §7 verdict algorithm (see §1 above) |
+
+---
+
+## 4. Budgets & Stop Conditions
+
+### Iteration and token caps
+
+| Cap | Setting key | Default |
+|-----|-------------|---------|
+| Quality-loop max iterations | `run.maxIterations` | 3 |
+| Auto-wait budget (rate-limit windows) | `run.autoWaitMinutes` | 0 (off) |
+
+When a cap is reached, the run stops at the human merge gate rather than continuing indefinitely.
+
+### Stop and hold states
+
+The workflow stops or holds at these states — do not attempt to continue past them:
+
+| State | Meaning | Action |
+|-------|---------|--------|
+| `waiting_for_human_merge` | All gates passed; PR is open | Human reviews and merges |
+| `awaiting_verification` | At least one AC is `PENDING` external verification | Wait for the external signal; see [`docs/features/qa-verdict-workflow-states.md`](../../docs/features/qa-verdict-workflow-states.md) |
+| `blocked` | A guard halted the run | Investigate the block; do not bypass |
+
+### Gap-prompt discipline
+
+**Diagnostic prompts are cheap and high-yield. Imperative prompts require triage first.**
+
+- **Diagnostic** ("what are the gaps?"): run freely. Surfaces unknowns at low cost.
+- **Imperative** ("fix all gaps"): requires triage first. An unfocused imperative prompt against a list of gaps produces shallow patches for every item rather than deep fixes for the real ones. The 2026-08 incident (#930) demonstrated this directly: an imperative "fix all gaps" run against a QA verdict produced 12 surface-level changes that passed re-QA but left the root-cause gap intact, requiring a third QA cycle.
+
+When QA returns gaps: run a diagnostic first ("which gap is the most blocking?"), then issue a targeted imperative for that gap specifically.
+
+---
+
+## 5. Stack-Specific Notes
 
 {{STACK_NOTES}}
 
-## Project-Specific Notes
+---
 
-<!-- Add your project-specific guidelines below -->
+## Project-Specific Notes
 
+<!-- Add your project-specific guidelines below this line.
+     This section is preserved across `sequant update` and `sync` runs
+     (it is in CUSTOMIZABLE_FILES). Everything above is updated automatically. -->

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:

package/templates/skills/loop/SKILL.md

@@ -59,7 +59,7 @@ When running as part of an orchestrated workflow (e.g., `sequant run` or `/fulls
 1. **Use provided worktree** - Work in `SEQUANT_WORKTREE` path directly
 2. **Use `SEQUANT_ISSUE`** - Skip issue number parsing from invocation
 3. **Reduce GitHub comment frequency** - Defer updates to orchestrator
-4. **Trust issue context** - Orchestrator has already validated issue
+4. **Trust embedded context** - when the orchestrator injected a `<!-- SEQUANT_PROMPT_CONTEXT -->` block into this invocation, it is the authoritative QA-findings source; do not re-fetch from GitHub (see Step 1A below)
 
 **Behavior when standalone (SEQUANT_ORCHESTRATOR is NOT set):**
 
@@ -81,10 +81,20 @@ When running as part of an orchestrated workflow (e.g., `sequant run` or `/fulls
 
 #### Step 1A: Orchestrated Mode (SEQUANT_ORCHESTRATOR is set)
 
-When `SEQUANT_ORCHESTRATOR` is set, read QA findings from the GitHub issue comments instead of a log file:
+<!-- BEGIN: step-1a-context-source (#960) -->
+
+**Check your own invocation first — before fetching anything.** The orchestrator (`ready-gate.ts` or `batch-executor.ts`, via `buildLoopContext`) may already have embedded the QA findings directly into the prompt that invoked this `/loop` run, wrapped in a `<!-- SEQUANT_PROMPT_CONTEXT -->` / `<!-- /SEQUANT_PROMPT_CONTEXT -->` sentinel pair (`getPhasePrompt`, `src/lib/workflow/phase-executor.ts`). When that sentinel is present in your own invocation text:
+
+- Treat the text between the markers as the authoritative QA findings (`qa_comment` below).
+- **Do not** fetch `gh issue view` for QA comments — skip straight to "Parsing QA comment" below, using the embedded text in place of the fetched comment.
+- **The embedded block's gap list IS your `recommendations`.** The block is not QA-comment-shaped — the parsing snippets below (verdict grep aside) won't extract anything from it. Read the list under `Gaps to address:` (ready-gate) or `QA Gaps:` (batch-executor) directly as the findings to fix; the `QA Verdict:` line is the verdict.
+- That gap list is already `fixableGaps`-filtered by the orchestrator (`selectFixableGaps` in `batch-executor.ts`, or ready-gate's own filter), so the `document`/`pause_for_human` exclusion in "Excluded Finding Classes" below is redundant for it — it exists for the fetched-comment fallback. But this applies **only to the gap list**: any `Suggestions:` or `Last output:` sections in the block (batch-executor only) are raw, unfiltered context — use them for understanding, never as additional findings to fix.
+
+**Only when the sentinel is absent** from your invocation — a standalone-style dispatch, or an orchestrator that doesn't inject `promptContext` — fall back to reading QA findings from the GitHub issue comments instead of a log file:
 
 ```bash
-# Check if we're in orchestrated mode
+# Fallback: no embedded SEQUANT_PROMPT_CONTEXT sentinel in the invocation.
+# Fetch QA findings from GitHub comments instead.
 if [[ -n "$SEQUANT_ORCHESTRATOR" ]]; then
   echo "Orchestrated mode detected (orchestrator: $SEQUANT_ORCHESTRATOR)"
 
@@ -96,6 +106,8 @@ if [[ -n "$SEQUANT_ORCHESTRATOR" ]]; then
 fi
 ```
 
+<!-- END: step-1a-context-source (#960) -->
+
 **How to identify QA comments:**
 
 | Pattern | Meaning |
@@ -103,7 +115,7 @@ fi
 | `## QA Review for Issue #N` | QA phase comment header |
 | `### Verdict:` | Contains AC_NOT_MET, AC_MET_BUT_NOT_A_PLUS, etc. |
 | `### AC Coverage` | Table with MET/NOT_MET/PARTIALLY_MET statuses |
-| `### Required Fixes` or `### Recommendations` | Actionable items to fix |
+| `<!-- SEQUANT_QA_GAPS: {...} -->` | Structured findings — the primary source for `recommendations` (#937; see below) |
 
 **Parsing QA comment:**
 
@@ -116,14 +128,58 @@ verdict=$(echo "$qa_comment" | grep -oE "Verdict:\s*\w+" | head -1 | awk '{print
 # Extract NOT_MET AC items
 not_met_acs=$(echo "$qa_comment" | grep -E "NOT_MET|PARTIALLY_MET" || true)
 
-# Extract recommendations section
-recommendations=$(echo "$qa_comment" | sed -n '/### Required Fixes/,/###/p' | head -n -1)
+# #937: prefer the structured SEQUANT_QA_GAPS marker over prose scraping.
+# `### Required Fixes` was removed — no QA output template ever emitted that
+# heading, so the old `sed -n '/### Required Fixes/,/###/p'` extraction was
+# dead code that always produced an empty `recommendations`. The marker's
+# payload is an array of objects, so a single node -e does the stripping,
+# matching, AND JSON.parse/filter in one script — instead of hand-rolled
+# jq/awk — mirroring the "do real parsing in TS/JS, keep shell to presence
+# checks" split from the #871 drift-guard lesson (the same taxonomy filter
+# also lives in `selectFixableGaps`, `src/lib/workflow/phase-executor.ts` —
+# this is the shell-side mirror for standalone/orchestrated-comment-scrape
+# mode, not a duplicate contract).
+#
+# Stripping fenced/inline code before matching mirrors `stripMarkdownCode`
+# (src/lib/workflow/phase-detection.ts) — a bare grep/sed would mistake a
+# marker quoted inside a code fence (e.g. this skill's own "QA Log Example"
+# below) for a real one. Latest-wins if more than one marker is present,
+# matching `parseQaGapsMarker`'s semantics.
+recommendations=$(printf '%s' "$qa_comment" | node -e '
+  let input = "";
+  process.stdin.on("data", (d) => (input += d));
+  process.stdin.on("end", () => {
+    const stripped = input
+      .replace(/`{3,}[\s\S]*?`{3,}|~{3,}[\s\S]*?~{3,}/g, "")
+      .replace(/`[^`\n]+`/g, "");
+    const matches = [...stripped.matchAll(/<!-- SEQUANT_QA_GAPS: (\{[\s\S]*?\}) -->/g)];
+    if (matches.length === 0) return;
+    try {
+      const payload = JSON.parse(matches[matches.length - 1][1]);
+      const findings = Array.isArray(payload.findings) ? payload.findings : [];
+      for (const f of findings) {
+        if (f.recommendedAction === "document" || f.recommendedAction === "pause_for_human") continue;
+        console.log(`- ${f.description}`);
+      }
+    } catch {
+      // Malformed marker JSON — leave recommendations empty, not a crash.
+    }
+  });
+' || true)
+
+# No marker (QA output predates #937, or emitted an empty findings array
+# with everything filtered) — fall back to the AC-table NOT_MET/PARTIALLY_MET
+# rows already captured above; there is no prose "Required Fixes" section to
+# scrape.
+if [[ -z "$recommendations" ]]; then
+  recommendations="$not_met_acs"
+fi
 ```
 
-**If no QA comment found in orchestrated mode:**
-1. Log a clear error: `"Warning: No QA comment found in issue #N"`
+**If neither an embedded `SEQUANT_PROMPT_CONTEXT` block nor a matching GitHub QA comment is found in orchestrated mode:**
+1. Log a clear error: `"Warning: No embedded context or QA comment found for issue #N"`
 2. Fall back to Step 1B (log file) as a recovery mechanism
-3. If log file also doesn't exist, exit with error
+3. If log file also doesn't exist, exit with error — do not silently report "no actionable issues"; a silent miss here is the exact failure mode this section exists to prevent (#960)
 
 #### Step 1B: Standalone Mode (no SEQUANT_ORCHESTRATOR)
 
@@ -178,13 +234,14 @@ Some QA findings are real but **not fixable by a code change**. Feeding them to
 | Class | Marker in the QA comment | Why it is not actionable |
 |-------|--------------------------|--------------------------|
 | Infra-blocked CI | `<!-- qa:ci-infra-blocked -->` | Every check failed without a runner ever starting (e.g. an Actions spending-limit lockout). The cause is account/infrastructure state; no diff can turn the checks green. See `qa/SKILL.md` § "Infra-Blocked CI Detection". |
+| `document`/`pause_for_human` findings | `<!-- SEQUANT_QA_GAPS: {...} -->`, per-finding `recommendedAction` | Quality/polish gaps deliberately deferred (`document`), or findings needing a human decision the loop can't make on its own (`pause_for_human`) — see #937. Filtered directly out of the `recommendations` extraction above (Step 1A), not by rebinding `qa_comment` — the marker's structure makes a per-finding filter more precise than a text-range delete. |
 
 ```bash
 # Drop the marked findings when QA flagged CI as infra-blocked, so its
 # NEEDS_VERIFICATION AC items are never mistaken for actionable findings.
 # Range is EXCLUSIVE of the next `### ` header — a `sed '/marker/,/^### /d'`
 # range would delete that header too and orphan the following section's
-# content (verified: it silently swallows `### Required Fixes`).
+# content (verified against this file's own `### AC Coverage` header).
 qa_comment_raw="$qa_comment"   # keep the original so the cause can be reported verbatim
 
 if echo "$qa_comment" | grep -q '<!-- qa:ci-infra-blocked -->'; then
@@ -513,13 +570,15 @@ For each iteration, output:
 
 ### Verdict: AC_NOT_MET
 
-### Required Fixes
+### Next Steps
 
 1. Complete URL validation in ExternalUrlTab
 2. Add focal point persistence in updateArticleImage action
+
+<!-- SEQUANT_QA_GAPS: {"findings":[{"category":"requirement_gap","evidence":"AC-3 row: PARTIALLY_MET — External URL validation incomplete","description":"Complete URL validation in ExternalUrlTab","recommendedAction":"fix_now","affectedAcs":["AC-3"]},{"category":"requirement_gap","evidence":"AC-4 row: NOT_MET — Focal point not persisted to database","description":"Add focal point persistence in updateArticleImage action","recommendedAction":"fix_now","affectedAcs":["AC-4"]}]} -->
 ```
 
-**Parsed Output:**
+**Parsed Output** (marker-derived — this is the real emission shape, see §"How to build the marker" in `qa/SKILL.md`):
 - Last phase: `/qa`
 - Verdict: `AC_NOT_MET`
 - Issues to fix: