sequant 2.10.0 → 2.11.0

package/templates/skills/fullsolve/SKILL.md

@@ -77,12 +77,17 @@ RIGHT: "Spec complete. Proceeding to exec..." [invokes /exec immediately]
 ├─────────────────────────────────────────────────────────────┤
 │                                                             │
 │  ┌─────────┐                                                │
-│  │  SPEC   │ Plan implementation, extract AC                │
+│  │  SPEC   │ Plan implementation, extract AC (main repo)    │
 │  └────┬────┘                                                │
 │       │                                                     │
 │       ▼                                                     │
 │  ┌─────────┐                                                │
-│  │  EXEC   │ Implement in feature worktree                  │
+│  │WORKTREE │ Create it here; export the resolved path       │
+│  └────┬────┘                                                │
+│       │                                                     │
+│       ▼                                                     │
+│  ┌─────────┐                                                │
+│  │  EXEC   │ Verify the path, then implement inside it      │
 │  └────┬────┘                                                │
 │       │                                                     │
 │       ▼                                                     │
@@ -166,7 +171,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 +255,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 +293,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:** 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.
+
+**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 +331,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 +360,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 +375,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 +453,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 +484,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 +557,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 +627,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 +726,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
@@ -699,16 +798,19 @@ 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:
+After the PR is created (or earlier if the workflow exits gracefully), 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 +909,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
@@ -930,7 +1035,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.

package/templates/skills/loop/SKILL.md

@@ -19,6 +19,7 @@ allowed-tools:
   - mcp__context7__*  # Library documentation - falls back to web search if unavailable
   - Bash(gh issue view:*)
   - Bash(gh issue comment:*)
+  - Bash(npx sequant worktree:*)
   - Bash(npm test:*)
   - Bash(npm run build:*)
   - Bash(git diff:*)
@@ -217,22 +218,64 @@ When the marker is absent this is a byte-identical pass-through, so unmarked QA
 ### Step 4: Locate Feature Worktree
 
 **If orchestrated (SEQUANT_WORKTREE is set):**
-- Use the provided worktree path directly: `cd $SEQUANT_WORKTREE`
-- Skip the lookup steps below
 
-**If standalone:**
+<!-- BEGIN: worktree-existence-guard (#899) -->
+
+**Verify the path before you use it. Never `cd` into it unchecked.** The value
+can name a worktree that was never created, or one belonging to a *different
+repository* — `../worktrees/` is one flat namespace shared by every repo under
+the same parent, and issue numbers are per-repo. A bare `cd` fails silently,
+and this skill **writes**: unguarded, it applies fixes and commits them in the
+main checkout, on whatever branch happens to be there.
 
-Find the worktree for this issue:
 ```bash
-git worktree list | grep -E "feature.*<issue-number>" || true
+npx sequant worktree verify "$SEQUANT_WORKTREE" --issue <issue-number> || {
+  echo "❌ HALT: SEQUANT_WORKTREE is not a usable worktree of this repository."
+  exit 1
+}
+cd "$SEQUANT_WORKTREE"
 ```
 
-Or check:
+`verify` exits non-zero with one of these named errors. **Every one of them is
+a halt** — report it and stop; never edit or commit from the current directory
+as a fallback:
+
+| Error | Meaning |
+|-------|---------|
+| `SEQUANT_WORKTREE_NOT_FOUND` | Path is empty, an unexpanded glob, or not an existing directory |
+| `SEQUANT_WORKTREE_FOREIGN` | Real directory, but not a worktree of *this* repository (another project's, or stale) |
+| `SEQUANT_WORKTREE_ISSUE_MISMATCH` | A worktree of this repo, but its branch belongs to a different issue |
+
+Once verify passes, skip the lookup steps below.
+
+<!-- END: worktree-existence-guard (#899) -->
+
+**If standalone:**
+
+<!-- BEGIN: worktree-standalone-lookup (#899) -->
+
+Resolve the worktree through git, not the filesystem:
+
 ```bash
-ls ../worktrees/feature/<issue-number>-*/
+WORKTREE="$(npx sequant worktree resolve <issue-number>)" || {
+  echo "❌ HALT: no worktree for #<issue-number> in this repository."
+  exit 1
+}
+cd "$WORKTREE"
 ```
 
-Navigate to the worktree directory for making fixes.
+`sequant worktree resolve` reads `git worktree list` in the current repository
+— which reports only *this* repo's worktrees — and selects on the **branch**
+git reports, not the directory name.
+
+**Do not glob `../worktrees/feature/<issue-number>-*`, and do not grep
+`git worktree list` for the issue number.** The first matches across sibling
+repositories, which share that directory; the second matches the printed path,
+so it keys on the directory slug — and a slug can drift from its own branch
+after a rename. Because this skill commits, landing in the wrong tree is
+destructive rather than merely wrong.
+
+<!-- END: worktree-standalone-lookup (#899) -->
 
 ### Step 5: Fix Identified Issues
 
@@ -511,12 +554,14 @@ Warning: No specific issues found in log.
 Recommend running /qa <N> for fresh assessment.
 ```
 
-**If worktree not found:**
+**If worktree not found** (`sequant worktree resolve` exited non-zero):
 ```
-Error: Feature worktree not found for issue #<N>
-Expected: ../worktrees/feature/<N>-*/
+Error: no worktree in this repository has a branch for issue #<N>
 Please run /exec <N> first to create the worktree.
 ```
+Report the resolver's own message (`WORKTREE_NOT_FOUND` or
+`WORKTREE_AMBIGUOUS`) rather than naming a filesystem path — the worktree is
+identified by its branch, not by a directory under `../worktrees/`.
 
 ## Configuration
 

package/templates/skills/merger/SKILL.md

@@ -6,6 +6,7 @@ metadata:
   author: sequant
   version: "1.0"
 allowed-tools:
+  - Bash(npx sequant worktree:*)
   - Bash(git:*)
   - Bash(gh pr:*)
   - Bash(gh issue:*)
@@ -99,6 +100,54 @@ When processing multiple issues, determine the execution mode for validation che
 
 ## Workflow
 
+### Acquire the Checkout Lock (REQUIRED)
+
+`/merger` runs branch-mutating git **in the main checkout**: `git checkout main`
+for the baseline in Step 0, then `git checkout -b integrate/…` and `git merge` on
+the integration path (Step 5), plus the mid-workflow `git checkout main` in
+Steps 6–7. Those verbs are global to the working tree, so before the first one
+you must claim the checkout lock (#901), exactly as `/fullsolve` does in its
+Phase 0.3. Without it a session on another issue can interleave a `git checkout`
+and land a merge on the wrong HEAD; and because the guard refuses a *non-holder*,
+an unparticipating `/merger` is itself refused when someone else holds the tree.
+
+`/merger` operates on several issues, so identify the holder by the **first issue
+number** passed to it and use that same `<first-issue>` on the acquire and on
+*every* release below — acquire and release must name the same holder or the
+release is refused against your own lock (#906). Substitute the literal number
+(e.g. `--issue=10` for `/merger 10 12`); a shell variable is invisible to the
+`pre-tool.sh` guard, which reads the command text before the shell expands it.
+
+```bash
+# Claim the shared working tree before the first branch-mutating verb.
+npx sequant locks checkout acquire \
+    --issue=<first-issue> \
+    --command="/merger <issue-numbers>" \
+    --skip-pid-check || true
+# Belt-and-suspenders for a parent that launched us with it; the guard's real
+# binding comes from watching the acquire command above (#906).
+export SEQUANT_ISSUE=<first-issue>
+```
+
+**`--issue` is mandatory** (#906): it is what proves you are the holder on
+release, since the acquiring shell's PID is gone by the next block
+(`--skip-pid-check`). Stale recovery is therefore age-based only (the 6h
+`SEQUANT_SKILL_LOCK_TTL_MS` and the 24h `SEQUANT_MAX_LOCK_AGE_MS` ceiling), not
+same-host dead-PID recovery.
+
+**Release contract:** release the checkout lock —
+`npx sequant locks checkout release --issue=<first-issue> || true` — on **every**
+path that exits `/merger`: happy-path completion (Step 8), the regression-gate
+halt (Step 7), and any error/abort in "Error Handling". Do **NOT** release on a
+branch that *continues* to a later branch-mutating verb (the #906 distinction):
+the integration `git merge` in Step 5 and the `git checkout main` in Steps 6–7
+run under the lock and must stay protected until the run ends.
+
+**Orchestrator/MCP mode:** when `SEQUANT_ORCHESTRATOR` is set, every `locks
+checkout` action is a no-op (exit 0, no file touched) and the `pre-tool.sh`
+checkout guard stands down, so the acquire/release calls are safe to run
+unconditionally.
+
 ### Step 0: Baseline Capture (REQUIRED)
 
 **Purpose:** Capture build error count and test pass/fail counts on main **before** any merge, so post-merge results can be compared to detect regressions.
@@ -157,8 +206,9 @@ fi
 For each issue specified:
 
 ```bash
-# Find the worktree for the issue
-git worktree list --porcelain | grep -A2 "feature/$ISSUE" || true
+# Find the worktree for the issue. Resolve by branch (#899/#904) — grepping
+# for "feature/$ISSUE" is a prefix match, so ISSUE=89 also hits feature/899-*.
+worktree_path=$(npx sequant worktree resolve "$ISSUE") || echo "No worktree for #$ISSUE"
 
 # Check PR status
 gh pr list --head "feature/$ISSUE-*" --json number,state,title
@@ -222,10 +272,16 @@ gh pr merge <PR_NUMBER> --squash
 
 # Only clean up worktree AFTER merge succeeds
 # If merge fails, the worktree is preserved so work isn't lost
-worktree_path=$(git worktree list | grep "feature/$ISSUE" | awk '{print $1}' || true)
-if [[ -n "$worktree_path" ]]; then
+#
+# Resolve by BRANCH, never by grepping the printed path (#899/#904): the path
+# line contains the directory slug, so `grep "feature/$ISSUE"` with ISSUE=89
+# also matches `feature/899-...` — and the next line force-removes whatever it
+# matched. `worktree resolve` matches the branch's issue number exactly, and
+# exits non-zero rather than guessing when nothing (or more than one) matches.
+if worktree_path=$(npx sequant worktree resolve "$ISSUE"); then
+  branch=$(git -C "$worktree_path" rev-parse --abbrev-ref HEAD)
   git worktree remove "$worktree_path" --force
-  git branch -D "feature/$ISSUE-"* 2>/dev/null || true
+  git branch -D "$branch" 2>/dev/null || true
 fi
 
 # Delete remote branch (previously handled by --delete-branch)
@@ -285,17 +341,23 @@ Read(file_path=".sequant/state.json")
 **After each successful merge, ensure the worktree is removed:**
 
 ```bash
-# Find and remove worktree for the issue
-worktree_path=$(git worktree list | grep "feature/$ISSUE" | awk '{print $1}' || true)
-if [[ -n "$worktree_path" ]]; then
+# Find and remove worktree for the issue.
+# Resolve by branch, not by grepping the printed path — see the note in the
+# clean-merge block above. This one force-removes, so a slug collision here
+# destroys an unrelated issue's worktree.
+if worktree_path=$(npx sequant worktree resolve "$ISSUE"); then
   echo "Removing worktree: $worktree_path"
   git worktree remove "$worktree_path" --force
 else
   echo "No worktree found for #$ISSUE (already cleaned up)"
 fi
 
-# Verify worktree removal
-git worktree list | grep -q "feature/$ISSUE" && echo "WARNING: Worktree still exists" || echo "✅ Worktree removed"
+# Verify worktree removal — resolve must now fail for this issue.
+if npx sequant worktree resolve "$ISSUE" >/dev/null 2>&1; then
+  echo "WARNING: Worktree still exists"
+else
+  echo "✅ Worktree removed"
+fi
 ```
 
 **Why this matters:** Leftover worktrees waste disk space and can cause confusion when re-running `sequant run` on the same issues. The state guard (#305) prevents re-execution, but the worktree should still be cleaned up.
@@ -387,6 +449,9 @@ if [[ "$REGRESSION_DETECTED" == "true" ]]; then
     echo "⚠️ REGRESSION DETECTED but --force flag set. Proceeding with merge."
     echo "⚠️ Acknowledgment: Merging despite $BUILD_DELTA new build error(s) and $TEST_FAIL_DELTA new test failure(s)."
   else
+    # Terminal halt — release the checkout lock before stopping (#901/#906).
+    # This branch does NOT continue to Step 8, so the release lives here.
+    npx sequant locks checkout release --issue=<first-issue> || true
     echo "❌ REGRESSION DETECTED — merge is blocked."
     echo ""
     echo "New build errors: $BUILD_DELTA"
@@ -460,6 +525,21 @@ git diff HEAD~1 --stat
 
 **Important:** Regression detection does NOT trigger automatic rollback. It reports for human decision-making.
 
+### Step 8: Release the Checkout Lock (REQUIRED)
+
+The merge is complete. Release the working-tree lock so other sessions can run
+branch-mutating git again (#901). Run this on the happy path — a successful merge
+and smoketest, or the `--force` proceed past a regression. It is the counterpart
+to the acquire in "Acquire the Checkout Lock" above.
+
+```bash
+npx sequant locks checkout release --issue=<first-issue> || true
+```
+
+On a *failure* exit instead, the release is done at the halt site — the
+regression gate (Step 7) or "Error Handling" — never both, so exactly one release
+runs per invocation.
+
 ## Dependency Detection
 
 Parse dependencies from issue body or comments:
@@ -579,6 +659,14 @@ gh pr view <PR_NUMBER> --json baseRefName,body | \
 
 ## Error Handling
 
+**Before halting on any failure below, release the checkout lock** (#901/#906) —
+the acquire in "Acquire the Checkout Lock" claimed the tree, and every failure
+here is a terminal exit that must hand it back before stopping:
+
+```bash
+npx sequant locks checkout release --issue=<first-issue> || true
+```
+
 **If validation fails:**
 - Report which issues failed validation
 - Suggest corrective actions

package/templates/skills/qa/SKILL.md

@@ -6,6 +6,7 @@ metadata:
   author: sequant
   version: "1.0"
 allowed-tools:
+  - Bash(npx sequant worktree:*)
   - Bash(npm test:*)
   - Bash(npm run build:*)
   - Bash(git diff:*)
@@ -362,15 +363,64 @@ Include in QA output when branch is stale:
 **QA Phase:** Review code in the feature worktree.
 
 **If orchestrated (SEQUANT_WORKTREE is set):**
-- Use the provided worktree path directly: `cd $SEQUANT_WORKTREE`
-- Skip step 1 below (worktree location provided by orchestrator)
+
+<!-- BEGIN: worktree-existence-guard (#899) -->
+
+**Verify the path before you use it. Never `cd` into it unchecked.** The value
+can name a worktree that was never created, or one belonging to a *different
+repository* — `../worktrees/` is one flat namespace shared by every repo under
+the same parent, and issue numbers are per-repo. A bare `cd` fails silently and
+leaves you reviewing the main checkout while reporting on the feature branch.
+
+```bash
+npx sequant worktree verify "$SEQUANT_WORKTREE" --issue <issue-number> || {
+  echo "❌ HALT: SEQUANT_WORKTREE is not a usable worktree of this repository."
+  exit 1
+}
+cd "$SEQUANT_WORKTREE"
+```
+
+`verify` exits non-zero with one of these named errors. **Every one of them is
+a halt** — report it and stop; do not fall back to reviewing the current
+directory, and do not emit a verdict for a tree you did not actually read:
+
+| Error | Meaning |
+|-------|---------|
+| `SEQUANT_WORKTREE_NOT_FOUND` | Path is empty, an unexpanded glob, or not an existing directory |
+| `SEQUANT_WORKTREE_FOREIGN` | Real directory, but not a worktree of *this* repository (another project's, or stale) |
+| `SEQUANT_WORKTREE_ISSUE_MISMATCH` | A worktree of this repo, but its branch belongs to a different issue |
+
+Once verify passes, skip step 1 below (worktree location provided by orchestrator).
+
+<!-- END: worktree-existence-guard (#899) -->
 
 **If standalone:**
 
+<!-- BEGIN: worktree-standalone-lookup (#899) -->
+
 1. **Locate the worktree:**
-   - The worktree should already exist from the execution phase (`/exec`)
-   - Find the worktree: `git worktree list` or check `../worktrees/feature/` for directories matching the issue number
-   - The worktree path will be: `../worktrees/feature/<issue-number>-<issue-title-slug>/`
+
+   The worktree should already exist from the execution phase (`/exec`).
+   Resolve it through git, not the filesystem:
+
+   ```bash
+   WORKTREE="$(npx sequant worktree resolve <issue-number>)" || {
+     echo "No worktree for #<issue-number> in this repository."
+     # Fall through to the "No Worktree Found" section below.
+   }
+   cd "$WORKTREE"
+   ```
+
+   `sequant worktree resolve` reads `git worktree list` in the current
+   repository — which reports only *this* repo's worktrees — and selects on the
+   **branch** git reports, not the directory name.
+
+   **Do not glob `../worktrees/feature/<issue-number>-*` to find it.** That
+   directory is shared by every sibling repository, so a name match may belong
+   to another project; and a directory slug can drift from its own branch after
+   a rename, so it proves nothing about which branch you would review.
+
+<!-- END: worktree-standalone-lookup (#899) -->
 
 2. **Check implementation status:**
    - Navigate to worktree: `cd <worktree-path>`
@@ -425,7 +475,10 @@ If no feature worktree exists (work was done directly on main):
 
 ```bash
 # 1. Check for worktree (indicates work may have started)
-worktree_path=$(git worktree list | grep -i "<issue-number>" | awk '{print $1}' | head -1 || true)
+# Resolve by branch, not by grepping the printed path (#899/#904): the path
+# line carries the directory slug, so a bare number match is both cross-issue
+# (89 matches 899-...) and slug-based rather than branch-based.
+worktree_path=$(npx sequant worktree resolve "<issue-number>" 2>/dev/null || true)
 
 # 2. Check for commits on feature branch (vs main) — include ALL file types
 commits_exist=$(git log --oneline origin/main..HEAD 2>/dev/null | head -1)