sequant 2.10.0 → 2.12.0

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
@@ -77,12 +82,17 @@ RIGHT: "Spec complete. Proceeding to exec..." [invokes /exec immediately]
 ├─────────────────────────────────────────────────────────────┤
 │                                                             │
 │  ┌─────────┐                                                │
-│  │  SPEC   │ Plan implementation, extract AC                │
+│  │  SPEC   │ Plan implementation, extract AC (main repo)    │
+│  └────┬────┘                                                │
+│       │                                                     │
+│       ▼                                                     │
+│  ┌─────────┐                                                │
+│  │WORKTREE │ Create it here; export the resolved path       │
 │  └────┬────┘                                                │
 │       │                                                     │
 │       ▼                                                     │
 │  ┌─────────┐                                                │
-│  │  EXEC   │ Implement in feature worktree                  │
+│  │  EXEC   │ Verify the path, then implement inside it      │
 │  └────┬────┘                                                │
 │       │                                                     │
 │       ▼                                                     │
@@ -120,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
@@ -146,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:
@@ -166,7 +201,7 @@ This skill acts as an **orchestrator** and sets environment variables for child
 
 **Child skills detect orchestration via `SEQUANT_ORCHESTRATOR` and adjust behavior:**
 - `/spec`: Runs normally (first phase, no prior context)
-- `/exec`: Skips worktree creation, uses provided path
+- `/exec`: Skips worktree creation, but still verifies the provided path before using it
 - `/test`: Skips issue fetch, trusts orchestrator context
 - `/qa`: Skips pre-flight sync, defers GitHub updates
 - `/loop`: Uses provided worktree, defers GitHub updates
@@ -250,9 +285,30 @@ Before creating any files, check if they already exist:
 
 **If work already exists:** Skip to the appropriate phase (e.g., if implementation is done, go to Phase 3 or 4).
 
-### 0.3 Acquire Concurrency Lock (#625)
+### 0.3 Acquire Concurrency Locks (#625, #901)
+
+**Before invoking `/spec`**, claim the per-issue concurrency lock.
+
+**Phase 0 always runs — including on a resumed run.** Smart Resumption (above) chooses only *which phase comes next after Phase 0*; it never skips Phase 0 itself. A resumed session that skipped the acquire below would hold neither lock while doing exactly the work the locks exist to protect, and would then run the release contract against a lock it never took.
 
-**Before invoking `/spec`**, claim the per-issue concurrency lock. This prevents a second session (another `/fullsolve`, an `npx sequant run`, or another `/fullsolve` in a different window) from racing on the same issue and producing zero-diff exec failures.
+**Declare the issue for the guard.** `pre-tool.sh` decides whether *you* are the checkout's holder by `sessionId` when both sides have one, then by `SEQUANT_ISSUE`, and finally by the session→issue binding it records for itself.
+
+```bash
+export SEQUANT_ISSUE=<issue-number>
+```
+
+**You do not need that export to be recognized as the holder (#906).** `PreToolUse` runs *outside and before* your command's shell, so nothing a skill bash block exports is visible to it — not even an export prepended to the same block as the guarded command. Instead the hook watches for `locks checkout acquire --issue=<N>` and records the binding itself, keyed on the session id, which is the one identity that survives the shell boundary killing the acquiring PID. The `export` above still helps a parent process that launched you with it; it is not what unblocks you.
+
+Consequences worth knowing:
+
+- After the acquire in this phase, branch-mutating git **in the main checkout is allowed for you** and still refused for every other session.
+- `git -C "$SEQUANT_WORKTREE" …` is exempt regardless, and is what every phase after 1.5 should be using anyway.
+- Path-restore (`git checkout -- <path>`) is exempt whether or not the path is quoted.
+- If the hook never observed your acquire (it was disabled, or the lock was taken by another tool), you are treated as a non-holder — release and re-acquire so the binding is recorded.
+
+**What this lock covers — and what it does not (#901).** The per-issue lock is keyed on the *issue number*. It prevents a second session from working on **the same issue** — another `/fullsolve <same-issue>`, an `npx sequant run <same-issue>`, or the same issue in a different window — and producing zero-diff exec failures.
+
+It is **not** a general concurrency guarantee. Two sessions working *different* issues take different lock files and never contend, even when they share one working tree. `git checkout`, `switch`, `reset`, `rebase`, `merge` and `cherry-pick` are global to a checkout, so the per-issue lock says nothing about them. That contention is covered by the separate **checkout lock** below.
 
 ```bash
 # Acquire lock for this issue. --skip-pid-check is required: the shell that
@@ -267,11 +323,26 @@ if ! npx sequant locks acquire <issue-number> \
 fi
 ```
 
-**Release contract:** Phase 5.5 releases the lock on the happy path. On ANY halt/abort branch (spec failure, exec exhausted, qa loop exhausted with AC_NOT_MET, unrecoverable error, stagnation halt), you MUST run `npx sequant locks release <issue-number> || true` **before** printing the halt message. The explicit release calls below cover the known branches; if you add a new abort path, add a release call there too.
+**Checkout lock (#901).** Claim the working tree as well, so a session on a *different* issue cannot run branch-mutating git in the same checkout. `pre-tool.sh` enforces this: a foreign session's `git checkout`/`switch`/`reset`/`rebase`/`merge`/`cherry-pick` in the main checkout is refused with a message naming the holder and its issue.
+
+```bash
+# Claim the shared working tree. Skip when you will work entirely inside a
+# feature worktree (`git -C <worktree> ...` is never blocked).
+npx sequant locks checkout acquire \
+    --issue=<issue-number> \
+    --command="/fullsolve <issue-number>" \
+    --skip-pid-check || true
+```
+
+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 (#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.
 
 **Backstop:** If a release is somehow missed, stale recovery clears the lock after 6h on the same host (`SEQUANT_SKILL_LOCK_TTL_MS` overrides). The user can also force-clear via `npx sequant locks clear <issue-number>`.
 
-**Orchestrator/MCP mode:** When `SEQUANT_ORCHESTRATOR` is set, `locks acquire` and `locks release` are no-ops (exit 0, no file touched). Safe to call unconditionally.
+**Orchestrator/MCP mode:** When `SEQUANT_ORCHESTRATOR` is set, `locks acquire`, `locks release` and every `locks checkout` action are no-ops (exit 0, no file touched), and the `pre-tool.sh` checkout guard stands down. Safe to call unconditionally.
 
 ## Phase 1: Planning (SPEC)
 
@@ -290,20 +361,20 @@ The `/spec` skill will:
 - Extract acceptance criteria (AC-1, AC-2, etc.)
 - Create implementation plan (3-7 steps)
 - Post plan comment to the issue
-- Create feature worktree
+
+`/spec` plans in the main repository and does **not** create a worktree — that
+is this skill's job, in Phase 1.5 below.
 
 ### 1.2 Capture Spec Output
 
 After `/spec` completes, extract and store:
 - **AC Checklist:** List of acceptance criteria for tracking
-- **Worktree Path:** Location for subsequent phases
 - **Recommended Phases:** Whether `/test` is needed (UI features)
 
 ```markdown
 ## Spec Output Captured
 
 **Issue:** #<N>
-**Worktree:** ../worktrees/feature/<issue-number>-*/
 **AC Count:** <N> items
 **Needs Testing:** Yes/No (based on labels)
 ```
@@ -319,6 +390,7 @@ If `/spec` fails:
 ```bash
 # Release before halting — see Phase 0.3 release contract.
 npx sequant locks release <issue-number> || true
+npx sequant locks checkout release --issue=<issue-number> || true
 ```
 
 ```markdown
@@ -333,7 +405,55 @@ Workflow halted. Fix the issue and re-run `/fullsolve <issue-number>`.
 **State after Phase 1:**
 - AC checklist defined
 - Implementation plan created (and posted to GitHub)
-- Feature worktree ready
+- Still in the main repository — no worktree exists yet
+
+**→ IMMEDIATELY proceed to Phase 1.5 (do not wait for user input)**
+
+## Phase 1.5: Create the Feature Worktree
+
+<!-- BEGIN: worktree-creation (#899) -->
+
+**This skill creates the worktree. Nothing upstream does it.** Every phase from
+here on runs inside it, and `SEQUANT_WORKTREE` is what tells the child skills
+where "here" is — so it must hold a **resolved absolute path**, never a glob.
+
+```bash
+# 1. Create it. Idempotent: exits 0 with "Worktree already exists" on re-entry
+#    (resumed session, retried phase), so this is safe to run unconditionally.
+./scripts/new-feature.sh <issue-number>
+
+# 2. Resolve the real path. `sequant worktree resolve` reads
+#    `git worktree list` in THIS repository and selects on the branch, so it
+#    can never return a sibling project's worktree — `../worktrees/` is one
+#    flat namespace shared by every repo under the same parent.
+SEQUANT_WORKTREE="$(npx sequant worktree resolve <issue-number>)" || {
+  echo "❌ Could not resolve a worktree for #<issue-number> after creating one."
+  npx sequant locks release <issue-number> || true
+  npx sequant locks checkout release --issue=<issue-number> || true
+  exit 1
+}
+export SEQUANT_WORKTREE
+echo "Worktree: $SEQUANT_WORKTREE"
+```
+
+**Never substitute a glob for this step.** `../worktrees/feature/<issue>-*/`
+is not a path: unquoted it may not expand at all, and where it does expand it
+matches on the directory slug, which is shared across repositories and can
+drift from its own branch after a rename.
+
+**If `new-feature.sh` fails** (dirty tree, branch conflict), release the lock
+and halt — do not proceed into Phase 2 in the main checkout:
+
+```bash
+npx sequant locks release <issue-number> || true
+npx sequant locks checkout release --issue=<issue-number> || true
+```
+
+<!-- END: worktree-creation (#899) -->
+
+**State after Phase 1.5:**
+- Feature worktree created and verified to belong to this repository
+- `SEQUANT_WORKTREE` exported as a resolved absolute path
 
 **→ IMMEDIATELY proceed to Phase 2 (do not wait for user input)**
 
@@ -363,12 +483,13 @@ Set environment variables before invoking `/exec` so it can optimize its behavio
 export SEQUANT_ORCHESTRATOR=fullsolve
 export SEQUANT_PHASE=exec
 export SEQUANT_ISSUE=<issue-number>
-export SEQUANT_WORKTREE=../worktrees/feature/<issue-number>-*/
+# Absolute path resolved in Phase 1.5 — never a glob.
+export SEQUANT_WORKTREE="$SEQUANT_WORKTREE"
 ```
 
 When `/exec` detects `SEQUANT_ORCHESTRATOR`, it:
-- Skips worktree creation (already done by `/spec`)
-- Uses the provided worktree path
+- Skips worktree creation (already done in Phase 1.5)
+- Verifies the provided path with `npx sequant worktree verify` before using it
 - Defers GitHub comment updates to orchestrator
 
 ### 2.3 Handle Exec Failures
@@ -393,6 +514,7 @@ while exec_iteration < MAX_EXEC_ITERATIONS:
 ```bash
 # Release before halting — see Phase 0.3 release contract.
 npx sequant locks release <issue-number> || true
+npx sequant locks checkout release --issue=<issue-number> || true
 ```
 
 ```markdown
@@ -465,7 +587,8 @@ The `/test` skill will:
 export SEQUANT_ORCHESTRATOR=fullsolve
 export SEQUANT_PHASE=test
 export SEQUANT_ISSUE=<issue-number>
-export SEQUANT_WORKTREE=../worktrees/feature/<issue-number>-*/
+# Absolute path resolved in Phase 1.5 — never a glob.
+export SEQUANT_WORKTREE="$SEQUANT_WORKTREE"
 ```
 
 When `/test` detects `SEQUANT_ORCHESTRATOR`, it:
@@ -534,7 +657,8 @@ The `/qa` skill will:
 export SEQUANT_ORCHESTRATOR=fullsolve
 export SEQUANT_PHASE=qa
 export SEQUANT_ISSUE=<issue-number>
-export SEQUANT_WORKTREE=../worktrees/feature/<issue-number>-*/
+# Absolute path resolved in Phase 1.5 — never a glob.
+export SEQUANT_WORKTREE="$SEQUANT_WORKTREE"
 ```
 
 When `/qa` detects `SEQUANT_ORCHESTRATOR`, it:
@@ -632,6 +756,11 @@ echo "Current branch: $CURRENT_BRANCH"
 
 # HARD GATE: Must be on a feature branch, not main/master
 if [[ "$CURRENT_BRANCH" == "main" || "$CURRENT_BRANCH" == "master" ]]; then
+  # Release before halting — see Phase 0.3 release contract. This gate fires
+  # later than any other exit path, so a leak here wedges the tree for the
+  # longest (#906).
+  npx sequant locks release <issue-number> || true
+  npx sequant locks checkout release --issue=<issue-number> || true
   echo "❌ ERROR: On $CURRENT_BRANCH — commits must NOT land on main."
   echo "   Fix: git checkout feature/<issue-number>-* or create a new branch."
   exit 1
@@ -664,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)
@@ -684,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
@@ -699,16 +838,26 @@ npx sequant doctor
 
 If any command fails, fix immediately on main before continuing. This catches issues like ESM compatibility bugs that unit tests may miss.
 
-### 5.5 Release Concurrency Lock (#625)
+### 5.5 Release Concurrency Locks (#625, #901)
 
-After the PR is created (or earlier if the workflow exits gracefully), release the lock so other sessions can claim it:
+**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
+npx sequant locks checkout release --issue=<issue-number> || true
 ```
 
 `|| true` is intentional — release is idempotent; the lock may already have been cleared (orchestrator mode, age-based recovery, or manual `locks clear`). The exit code is informational only.
 
+**But read it if you are debugging (#906).** A non-zero exit from `locks checkout release` no longer means only "nothing was held". It now also means **"held, but not by you"** — a refusal, printed with the holder's issue and the `clear --force` recovery command. If you see that after your own run, the usual cause is a missing or wrong `--issue`, not a stale lock.
+
 ## Iteration Tracking
 
 Track iterations to prevent infinite loops:
@@ -807,13 +956,16 @@ Ready for human review and merge.
 
 ## Error Recovery
 
-**Concurrency lock cleanup (#625, applies to every abort path below):**
+**Concurrency lock cleanup (#625, #901, applies to every abort path below):**
 
 ```bash
 npx sequant locks release <issue-number> || true
+npx sequant locks checkout release --issue=<issue-number> || true
 ```
 
-Run this BEFORE printing the halt/exit message in any of the branches below. The release call is idempotent (no-op when nothing is held, no-op in orchestrator mode), so calling it unconditionally on every error path is safe.
+Run this BEFORE printing the halt/exit message in any branch below that **exits the workflow**. The release call is idempotent (no-op when nothing is held, no-op in orchestrator mode), so calling it unconditionally on a genuine exit path is safe.
+
+Do **not** run it on the two branches below that continue to Phase 5 — "test loop exhausted" and "QA loop exhausted" both go on to create a PR, and releasing there hands the tree away while this session is still using it.
 
 **If spec fails:**
 - Check issue exists and is readable
@@ -844,6 +996,7 @@ Run this BEFORE printing the halt/exit message in any of the branches below. The
 | 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
 
@@ -888,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:
@@ -930,7 +1088,8 @@ As an orchestrator, `/fullsolve` must:
    export SEQUANT_ORCHESTRATOR=fullsolve
    export SEQUANT_PHASE=<current-phase>
    export SEQUANT_ISSUE=<issue-number>
-   export SEQUANT_WORKTREE=<worktree-path>
+   # Resolved in Phase 1.5 via `sequant worktree resolve` — absolute, never a glob.
+   export SEQUANT_WORKTREE="$SEQUANT_WORKTREE"
    ```
 
 2. **State tracking** is handled automatically by the orchestrator runtime when `SEQUANT_ORCHESTRATOR` is set. Child skills defer state management to the orchestrator to avoid duplicate updates.