sequant 2.11.0 → 2.13.0

package/dist/marketplace/external_plugins/sequant/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:*)
@@ -58,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):**
 
@@ -80,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)"
 
@@ -95,6 +106,8 @@ if [[ -n "$SEQUANT_ORCHESTRATOR" ]]; then
 fi
 ```
 
+<!-- END: step-1a-context-source (#960) -->
+
 **How to identify QA comments:**
 
 | Pattern | Meaning |
@@ -102,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:**
 
@@ -115,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)
 
@@ -177,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
@@ -217,22 +275,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
 
@@ -470,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:
@@ -511,12 +613,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/dist/marketplace/external_plugins/sequant/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,47 @@ 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.
+
+<!-- BEGIN: named-set-boundary (#961) -->
+## Named-Set Boundary (REQUIRED)
+
+`/merger <issue-numbers>` is the user's consent to merge **exactly those
+issues** — invoking it is the explicit authorization, the same way `sequant
+merge`/`sequant merge --watch` are explicit and human-triggered (#958's
+Non-Goals). That consent does not extend past the named set: never let
+Dependency Detection or Stacked PR Detection below pull an**other** issue's PR
+into `gh pr merge` just because it happens to unblock or precede a named one.
+
+**Rule:** if merge ordering requires a PR whose issue number is **not** in the
+invocation's arg list, halt before merging anything and report it — do not
+widen the merge silently, and do not treat the stacked-PR "Continue anyway?
+(y/N)" confirmation as license to include an unnamed predecessor. Offer the
+widened command for the user to re-run:
+
+```text
+❌ Out-of-named-set dependency
+   #101 depends on #100, but #100 was not in your /merger invocation.
+   Halting before any merge.
+   To include it: /merger 100 101
+```
+
+This rule governs both sections below.
+<!-- END: named-set-boundary (#961) -->
+
 ## Dependency Detection
 
 Parse dependencies from issue body or comments:
@@ -477,7 +583,9 @@ Labels: depends-on/10
 gh issue view <issue> --json body,labels | jq '.body, .labels[].name'
 ```
 
-If dependencies found, enforce merge order.
+If dependencies found, enforce merge order **among the named set**. If a
+dependency's issue number falls outside the named set, apply the Named-Set
+Boundary rule above: halt and report instead of merging it.
 
 ### Stacked PR Detection (#605)
 
@@ -498,8 +606,9 @@ gh pr view <PR_NUMBER> --json baseRefName,body | \
 
 1. Extract the stack manifest from each PR's body (`Part of stack: #100 → #101 (this) → #102`).
 2. Treat the order in the manifest as the merge order — earlier entries land first.
-3. If the user requests an out-of-order merge (e.g. `/merger 102 100 101` for the stack above), **warn before proceeding** and recommend the manifest order.
-4. GitHub auto-updates the dependent PR's base when its predecessor merges, so once the order is correct no manual rebasing is needed.
+3. If **every** predecessor is in the named set but requested out of order (e.g. `/merger 102 100 101` for the stack above), **warn before proceeding** and recommend the manifest order.
+4. If a predecessor is **not** in the named set at all (e.g. `/merger 102` alone for that stack), the Named-Set Boundary rule applies: halt and report — do not fall through to the "Continue anyway? (y/N)" prompt, since that prompt is for reordering named issues, not for merging an unnamed one.
+5. GitHub auto-updates the dependent PR's base when its predecessor merges, so once the order is correct no manual rebasing is needed.
 
 **Warning template:**
 
@@ -579,6 +688,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