sequant 2.7.0 → 2.9.0

package/templates/scripts/cleanup-worktree.sh

@@ -1,8 +1,20 @@
 #!/bin/bash
 
 # Clean up a worktree after PR is merged
-# Usage: ./scripts/cleanup-worktree.sh <branch-name>
+# Usage: ./scripts/cleanup-worktree.sh [flags] <branch-name>
 # Example: ./scripts/cleanup-worktree.sh feature/123-add-user-dashboard
+#
+# The remote branch is deleted ONLY when the branch's PR is MERGED (the
+# documented post-merge contract) or when an explicit override flag is passed.
+# Local teardown (worktree + local branch) always runs so the branch lock is
+# freed for a subsequent `gh pr merge --delete-branch`.
+#
+# Flags:
+#   -y, --yes         Skip the confirmation prompt (non-interactive confirm).
+#                     Does NOT override the merge gate on remote deletion.
+#   --delete-remote   Override the merge gate and delete the remote branch even
+#                     when the PR is not merged (still honors the TTY confirm).
+#   --force           Implies both --yes and --delete-remote.
 
 set -e
 
@@ -13,7 +25,65 @@ YELLOW='\033[1;33m'
 RED='\033[0;31m'
 NC='\033[0m'
 
-BRANCH_NAME=$1
+# Print CLI usage/help (kept in sync with the header comment above).
+print_usage() {
+    cat <<'USAGE'
+Usage: ./scripts/cleanup-worktree.sh [flags] <branch-name>
+
+Clean up a feature worktree. The remote branch is deleted ONLY when the
+branch's PR is MERGED (the documented post-merge contract) or when an
+explicit override flag is passed. Local teardown (worktree + local branch)
+always runs so the branch lock is freed for a subsequent
+`gh pr merge --delete-branch`.
+
+Flags:
+  -y, --yes         Skip the confirmation prompt (non-interactive confirm).
+                    Does NOT override the merge gate on remote deletion.
+  --delete-remote   Override the merge gate and delete the remote branch even
+                    when the PR is not merged (still honors the confirm gate).
+  --force           Implies both --yes and --delete-remote.
+  -h, --help        Show this help and exit.
+
+Example:
+  ./scripts/cleanup-worktree.sh feature/123-add-user-dashboard
+USAGE
+}
+
+# Parse flags. ASSUME_YES bypasses the confirmation prompt; DELETE_REMOTE
+# overrides the merge gate on remote deletion. The first non-flag argument is
+# the branch name. --force is the combined opt-in (both behaviors).
+BRANCH_NAME=""
+ASSUME_YES=false
+DELETE_REMOTE=false
+while [ $# -gt 0 ]; do
+    case "$1" in
+        -y|--yes)
+            ASSUME_YES=true
+            ;;
+        --delete-remote)
+            DELETE_REMOTE=true
+            ;;
+        --force)
+            ASSUME_YES=true
+            DELETE_REMOTE=true
+            ;;
+        -h|--help)
+            print_usage
+            exit 0
+            ;;
+        -*)
+            echo -e "${RED}❌ Error: Unknown flag: $1${NC}" >&2
+            print_usage >&2
+            exit 1
+            ;;
+        *)
+            if [ -z "$BRANCH_NAME" ]; then
+                BRANCH_NAME="$1"
+            fi
+            ;;
+    esac
+    shift
+done
 
 # Resolve main worktree (first entry in porcelain output) so subsequent git
 # commands run from a stable cwd even if the caller invoked us from inside the
@@ -23,11 +93,11 @@ MAIN_WORKTREE=$(git worktree list --porcelain | sed -n 's/^worktree //p' | head
 
 # Check if branch name provided
 if [ -z "$BRANCH_NAME" ]; then
-    echo -e "${RED}❌ Error: Branch name required${NC}"
-    echo "Usage: ./scripts/cleanup-worktree.sh <branch-name>"
-    echo ""
-    echo "Active worktrees:"
-    git worktree list
+    echo -e "${RED}❌ Error: Branch name required${NC}" >&2
+    print_usage >&2
+    echo "" >&2
+    echo "Active worktrees:" >&2
+    git worktree list >&2
     exit 1
 fi
 
@@ -58,12 +128,24 @@ echo ""
 # Check if PR is merged
 PR_STATUS=$(gh pr list --head "$BRANCH_NAME" --state merged --json number,state --jq '.[0].state' 2>/dev/null || echo "")
 
+# Confirmation gate — only reached when the PR is NOT merged. When MERGED we
+# short-circuit past this entirely (no prompt, no TTY check) so the documented
+# post-merge happy path is unchanged.
 if [ "$PR_STATUS" != "MERGED" ]; then
     echo -e "${YELLOW}⚠️  Warning: PR for this branch is not merged${NC}"
-    read -p "Are you sure you want to delete this worktree? (y/n) " -n 1 -r
-    echo
-    if [[ ! $REPLY =~ ^[Yy]$ ]]; then
-        echo -e "${BLUE}Cancelled.${NC}"
+    if [ "$ASSUME_YES" = true ]; then
+        echo -e "${BLUE}Proceeding (--yes/--force).${NC}"
+    elif [ -t 0 ]; then
+        read -p "Are you sure you want to delete this worktree? (y/n) " -n 1 -r
+        echo
+        if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+            echo -e "${BLUE}Cancelled.${NC}"
+            exit 0
+        fi
+    else
+        # Non-interactive (no TTY) and no confirm flag: exit safely instead of
+        # stalling on `read`. Pass --yes/--force to proceed without a prompt.
+        echo -e "${BLUE}Non-interactive context and PR not merged — pass --yes or --force to proceed. Exiting without changes.${NC}"
         exit 0
     fi
 fi
@@ -101,9 +183,16 @@ git worktree remove "$WORKTREE_PATH" --force
 echo -e "${BLUE}🌿 Deleting local branch...${NC}"
 git branch -D "$BRANCH_NAME" 2>/dev/null || true
 
-# Delete remote branch
-echo -e "${BLUE}☁️  Deleting remote branch...${NC}"
-git push origin --delete "$BRANCH_NAME" 2>/dev/null || true
+# Delete remote branch — hard-gated on merge state. Only delete when the PR is
+# MERGED or an explicit override flag (--delete-remote/--force) was passed.
+# Otherwise leave the remote branch (and any open PR) intact: deleting an open
+# PR's head branch makes GitHub close the PR unmerged, stranding the work.
+if [ "$PR_STATUS" = "MERGED" ] || [ "$DELETE_REMOTE" = true ]; then
+    echo -e "${BLUE}☁️  Deleting remote branch...${NC}"
+    git push origin --delete "$BRANCH_NAME" 2>/dev/null || true
+else
+    echo -e "${YELLOW}⏭️  Skipped remote-branch delete (PR not merged; pass --delete-remote or --force to override).${NC}"
+fi
 
 # Update main
 echo -e "${BLUE}📥 Updating main branch...${NC}"

package/templates/skills/_shared/references/force-push.md

@@ -0,0 +1,34 @@
+# Force-push handoff pattern
+
+When you encounter `HOOK_BLOCKED: Force push` from `.claude/hooks/pre-tool.sh:106-111`, **do not attempt to bypass the hook**. The block is intentional — force-pushing rewrites history and can destroy work for others sharing the branch.
+
+## The pattern: hand the command to the user
+
+When a force push is genuinely required (e.g., cleaning contamination off a feature branch after a clean rebase), present the exact command to the user prefixed with `!` so they execute it in-session:
+
+```
+! git push --force-with-lease origin feature/<branch>
+```
+
+The user pastes that into the prompt; the `!` runs it in their shell, output streams back into the conversation, and you continue from there.
+
+**Always prefer `--force-with-lease` over raw `--force`.** `--force-with-lease` refuses to overwrite the remote ref if someone else pushed in the meantime, turning a silent stomp into a clean error.
+
+## Why bypass attempts fail
+
+`CLAUDE_HOOKS_DISABLED=true git push --force ...` does **not** work. The hook reads `CLAUDE_HOOKS_DISABLED` at the harness level *before* Bash executes the command, so prefixing the env var inside the command line has no effect. Setting it via `export` in a prior tool call doesn't help either — each Bash tool call is a fresh subprocess.
+
+## When force push is legitimate vs. not
+
+| Legitimate | Not legitimate |
+|------------|----------------|
+| Cleaning rebase contamination off your own feature branch before PR | Rewriting history on `main`/`master` |
+| Removing accidentally-committed secrets after rotation | "Squashing for cleanliness" on a shared branch |
+| Recovering from a mistakenly-pushed merge commit | Force-pushing over someone else's work |
+
+For shared branches, prefer `git revert` over force push.
+
+## Reference
+
+- Block definition: `.claude/hooks/pre-tool.sh:106-111`
+- Regex: `git push.*(--force| -f($| ))` — note this can also match the literal strings inside quoted `gh issue/pr` bodies (workaround: write the body to a file first)

package/templates/skills/assess/SKILL.md

@@ -69,6 +69,20 @@ If the output is non-empty, paste every line verbatim above the dashboard table
 
 The orchestrator/MCP mode (`SEQUANT_ORCHESTRATOR` set) returns no output, so the call is safe to make unconditionally.
 
+**Command prefix (#740, read-only):**
+
+Probe once here for a global/PATH `sequant`, and reuse the result for every emitted run command below. `npx sequant` is the invocation most prone to version skew (a dual node prefix plus npx cache reuse can silently run a *stale* binary while a directly-installed `sequant` on PATH is current), so prefer a resolvable global install when one exists.
+
+```bash
+# Resolve CMD_PREFIX once here; reuse it for every emitted run command below.
+command -v sequant >/dev/null 2>&1 && CMD_PREFIX="sequant" || CMD_PREFIX="npx sequant"
+```
+
+- Global install on PATH → `CMD_PREFIX="sequant"` → emit `sequant run …`
+- No global install (npx-only) → `CMD_PREFIX="npx sequant"` → emit `npx sequant run …` (unchanged default — zero behavior change for npx-only users)
+
+The probe is read-only and side-effect-free, so it runs unconditionally, including in orchestrator/MCP mode (`SEQUANT_ORCHESTRATOR` set).
+
 **From GitHub (parallel for all issues):**
 
 ```bash
@@ -182,11 +196,10 @@ Triggers (any one):
 - Issue body or comments mention `"depends on #N"`, `"blocked by #N"`, or `"after #N"`
 - One issue's described output is another issue's input (e.g., A changes a function signature that B consumes)
 
-Format: `Chain: npx sequant run <N1> <N2> --chain --qa-gate -Q <phases>   # alternative — <one-line reason>`
+Format: `Chain: <CMD_PREFIX> run <N1> <N2> --chain -Q <phases>   # alternative — <one-line reason>` (`<CMD_PREFIX>` resolved in Step 1)
 
 Flag references:
 - `--chain` chains issues (each branches from previous; implies `--sequential`)
-- `--qa-gate` pauses chain on QA failure (requires `--chain`)
 - `--base <branch>` — issue references a feature branch
 
 ### Step 5: Conflict Detection
@@ -233,15 +246,15 @@ False-positive guards and tunables (excluded paths, the path regex, the slash-co
 ...
 ────────────────────────────────────────────────────────────────
 Commands:
-  npx sequant run <N1> <N2> <flags>
-  npx sequant run <N3> <flags>              # resume
+  <CMD_PREFIX> run <N1> <N2> <flags>
+  <CMD_PREFIX> run <N3> <flags>              # resume
 ────────────────────────────────────────────────────────────────
 Order: <N> → <N> (<dependency reason>)
 
 ⚠ #<N>  <warning>
 ⚠ #<N>  <warning>
 
-Chain: npx sequant run <N1> <N2> --chain --qa-gate -Q <phases>   # alternative — <reason>
+Chain: <CMD_PREFIX> run <N1> <N2> --chain -Q <phases>   # alternative — <reason>
 
 Flags:
   <flag>                <one-line reason>
@@ -286,6 +299,7 @@ The commands block is headed by `Commands:` — no box-drawing, no character cou
 6. If ALL issues share the same workflow, emit a single command
 7. **Line splitting:** When a single command would contain more than 6 issue numbers, split into multiple commands of at most 6 issues each, grouped by compatible workflow. Example: 11 issues → two commands (6 + 5)
 8. **Minimal flags:** Omit `--phases` when the resulting workflow equals the CLI default (registered at `bin/cli.ts:186`, defined as `DEFAULT_PHASES` in `src/lib/workflow/types.ts`). Prefer additive flags over restating phases — additive flags: `--testgen` and `--security-review` (`bin/cli.ts:208-209`). Use `--testgen` instead of `--phases spec,testgen,exec,qa` (or `…,testgen,…,test,qa` for ui-labelled issues, since `phase-mapper.determinePhasesForIssue` auto-adds `test` from the ui label). Use `--security-review` instead of `--phases spec,security-review,exec,qa`. The posted marker (`<!-- assess:phases=… -->`) records the full resolved workflow regardless — markers are machine-readable, displayed commands are human shorthand. This intentional divergence is fine: parsers consume markers, humans copy commands.
+9. **Command prefix:** Substitute the Step-1 `CMD_PREFIX` for **every** emitted `sequant run` command — the Commands block, the `Chain:` line, and both single-issue detail-mode commands (PROCEED and the REWRITE "fresh start"). `Cleanup:` commands are `git`/`gh`, not `sequant`, so they are unaffected. A resolvable global `sequant` on PATH yields `sequant run …`; npx-only yields `npx sequant run …` (the default). Never mix prefixes within a single assessment.
 
 #### Annotation Rules
 
@@ -303,7 +317,7 @@ Emit annotations in this order between the separators that follow `Commands:`:
   - `⚠ #412  bug + auth labels — domain label (auth) takes priority over bug`
 
 - **`Chain:`** — Only when 2+ PROCEED issues have a detected dependency (see "Chain detection" in Step 4). Suggests an alternative execution topology. Does not replace the default per-issue commands. Format:
-  `Chain: npx sequant run <N1> <N2> --chain --qa-gate -Q <phases>   # alternative — <one-line reason>`
+  `Chain: <CMD_PREFIX> run <N1> <N2> --chain -Q <phases>   # alternative — <one-line reason>` (`<CMD_PREFIX>` resolved in Step 1)
 
 - **`Flags:`** — Only when non-default flags appear in the commands and the reason isn't obvious. One line per **distinct** flag used across all commands. Omit entire section when `-Q` is the only non-default flag AND its reason is obvious (e.g., all issues are enhancements). Format:
   ```
@@ -321,6 +335,8 @@ Emit annotations in this order between the separators that follow `Commands:`:
 
 Not all issues have explicit `- [ ]` checkboxes, so the `ACs` column is omitted.
 
+> **Prefix in examples:** The worked examples in this doc show the `npx sequant` default (the zero-install path). When the Step-1 probe resolves a global `sequant` on PATH, `CMD_PREFIX="sequant"` and every emitted command uses `sequant run …` instead — consistently within one assessment (see Commands Block Rule #9).
+
 ```
  #    Action     Reason                              Run
  462  PARK       Manual measurement task              ‖
@@ -385,7 +401,7 @@ Order: 185 → 186 (185 changes fetchApi error format that 186 consumes)
 ⚠ #185  Domain errors already exist in repository layer — scope may be smaller than expected
 ⚠ #186  @tanstack/react-query not installed; large scope (9 hooks + optimistic updates)
 
-Chain: npx sequant run 185 186 --chain --qa-gate -Q --testgen
+Chain: npx sequant run 185 186 --chain -Q --testgen
        # alternative — use if 186 should branch from 185's work
 
 Flags:
@@ -485,7 +501,7 @@ More context since you're focused on one issue. Separators between every section
 → PROCEED — <one-line reason>
 
 Commands:
-  npx sequant run <N> <flags>
+  <CMD_PREFIX> run <N> <flags>
 
 <phases> · <N> ACs
 
@@ -617,7 +633,7 @@ Need: <specific information required>
 → REWRITE — <reason>
 
 Commands:
-  npx sequant run <N> <flags>                 # fresh start
+  <CMD_PREFIX> run <N> <flags>                 # fresh start
 
 <phases> · <N> ACs
 ────────────────────────────────────────────────────────────────
@@ -652,16 +668,97 @@ Every separator and section is conditional. If there are no warnings, no chain,
 
 After displaying output, prompt the user to save using `AskUserQuestion` with options "Yes (Recommended)" and "No".
 
-If confirmed, post a structured comment to each issue via `gh issue comment`. Each posted comment should include:
-- **Supersession header** (when priors exist): If `findAllAssessComments` returned ≥1 prior, prepend `buildSupersessionHeader(priors)` immediately above the `→ ACTION — reason` line. When `detectChurn(...).isChurn === true`, also emit a `⚠ Re-assessed N times since <firstDate> without execution — possible blocker or low priority` warning in the dashboard. When `shouldPromptOnConflict(prior, new) === true`, confirm with the user via `AskUserQuestion` before posting. See "Prior Assessment Detection" in Step 1 for full protocol.
-- The action headline (`→ ACTION — reason`)
-- The workflow (for PROCEED/REWRITE)
-- Standard HTML markers on separate lines:
-  ```
-  <!-- assess:action=PROCEED -->
-  <!-- assess:phases=spec,exec,qa -->
-  <!-- assess:quality-loop=true -->
-  ```
+If confirmed, post a structured comment to each issue via `gh issue comment`. **Each posted comment is rendered with the single-mode template that matches that issue's verdict** — the same `#### PROCEED / CLOSE / CLARIFY / PARK / MERGE / REWRITE` templates defined under [Single Mode (1 issue)](#single-mode-1-issue) above. There is no separate, thinner shape for posted comments: the batch **dashboard** in chat and the **posted comment** on each issue are the only two formats, and the posted comment always reuses the single-mode template for its verdict. (Note: this is *not* a reversal of #453 — the single-mode templates are themselves the streamlined, scan-friendly format.)
+
+Render each comment as follows:
+
+1. **Pick the template by verdict.** For issue `#N`'s action, use the matching single-mode template (`#### PROCEED`, `#### REWRITE`, etc.) and fill it exactly as single mode would, including — where that template defines them:
+   - the `#<N> — <Title>` / `<State> · <labels>` header,
+   - the section separators the template defines,
+   - the `Commands:` block with the **resolved `CMD_PREFIX`** (Step-1 probe — `sequant` when a global is on PATH, else `npx sequant`) and the **real current flags** for that issue. When the dashboard batched several issues onto one `run` line (e.g. `run 461 460 458 443 -Q`), restate just `#N`'s own single-issue invocation (`run 458 -Q`): the shared flags that applied to `#N`, plus any per-issue flags the dashboard listed separately for it (e.g. `#412`'s `--security-review`, `#411`'s `--phases exec,qa`),
+   - the `<phases> · <N> ACs` line,
+   - for **CLOSE**, the `Cleanup:` block populated with just `#N`'s cleanup commands, de-aggregated from the dashboard's combined `Cleanup:` block.
+
+   Reference these templates rather than re-copying their bodies here — they are the single source of truth (avoids drift). Verdicts whose template omits a field (CLOSE / CLARIFY / PARK / MERGE have no `Commands:` or `<phases> · <N> ACs` line) simply omit it, exactly as the template shows.
+
+2. **Carry per-issue warnings.** Any `⚠` line from the batch dashboard that concerns `#N` (collision/conflict, churn, staleness, dual-concern, partial-AC) is carried into that issue's comment, with the leading `#N` dropped (the comment is already scoped to that issue). Placement depends on whether the verdict's template defines a warning slot:
+   - **PROCEED / REWRITE** — the template already defines a `⚠ ...` region between its two trailing separators; place the warning there.
+   - **CLOSE / CLARIFY / PARK / MERGE** — these templates have no `⚠` region (just a single trailing separator before the markers). Add the warning as its own separator-delimited block immediately above the marker block, so the tail reads: `<trailing separator>` → `⚠ ...` → `<separator>` → `<!-- assess:action=... -->`. This is the sole case where a posted comment extends a slot-less template; every other field still follows Step 1's "omit what the template omits." When an issue has no `⚠`, the template is emitted unchanged.
+
+3. **Supersession header** (when priors exist): If `findAllAssessComments` returned ≥1 prior, prepend `buildSupersessionHeader(priors)` immediately above the `→ ACTION — reason` line. When `detectChurn(...).isChurn === true`, also emit the `⚠ Re-assessed N times since <firstDate> without execution — possible blocker or low priority` warning in the warning slot (per step 2). When `shouldPromptOnConflict(prior, new) === true`, confirm with the user via `AskUserQuestion` before posting. See "Prior Assessment Detection" in Step 1 for full protocol.
+
+4. **Machine markers.** The posted comment keeps the single-mode **3-line** marker block — one directive per line, and only those directives the verdict defines:
+   ```
+   <!-- assess:action=PROCEED -->
+   <!-- assess:phases=spec,exec,qa -->
+   <!-- assess:quality-loop=true -->
+   ```
+   Do **not** use the batch dashboard's compact one-line marker (`<!-- #N assess:action=… assess:phases=… -->`) in a posted comment — that form is for the chat dashboard only.
+
+The chat batch dashboard is unchanged — this step governs only what lands on each issue.
+
+### Batch: dashboard vs posted comment
+
+A batch run shows one scannable dashboard in chat, then posts one single-mode comment per issue. The two are distinct by design: the dashboard is a triage table across all issues; each comment is the full single-mode assessment for that one issue.
+
+Dashboard (chat) — excerpt for #458:
+
+```
+ #    Action     Reason                              Run
+ 458  PROCEED    Parallel UX + race condition          spec → exec → qa
+────────────────────────────────────────────────────────────────
+Commands:
+  npx sequant run 458 -Q
+────────────────────────────────────────────────────────────────
+⚠ #458  Dual concern (UX + race) across 4 files
+
+Flags:
+  -Q     dual concern across 4 files
+────────────────────────────────────────────────────────────────
+
+<!-- #458 assess:action=PROCEED assess:phases=spec,exec,qa assess:quality-loop=true -->
+```
+
+Posted comment on issue #458 (single-mode PROCEED template — `#N` dropped from the warning, 3-line markers):
+
+```
+#458 — Parallel run UX freeze + reconcileState race condition
+Open · bug, enhancement, cli
+────────────────────────────────────────────────────────────────
+
+→ PROCEED — Both root causes confirmed in codebase
+
+Commands:
+  npx sequant run 458 -Q
+
+spec → exec → qa · 8 ACs
+
+Flags:
+  -Q     dual concern across 4 files
+────────────────────────────────────────────────────────────────
+⚠ Dual concern (UX + race) across 4 files
+────────────────────────────────────────────────────────────────
+
+<!-- assess:action=PROCEED -->
+<!-- assess:phases=spec,exec,qa -->
+<!-- assess:quality-loop=true -->
+```
+
+For a verdict whose template has no `⚠` slot, the carried warning becomes its own separator-delimited block above the markers (Step 2). Posted comment on a **PARK** issue the churn detector flagged:
+
+```
+#530 — Measure real-world assess latency across 20 repos
+Open · task, needs-data
+────────────────────────────────────────────────────────────────
+
+→ PARK — Blocked on manual measurement not yet scheduled
+  Resume after: latency sampling run completes
+────────────────────────────────────────────────────────────────
+⚠ Re-assessed 3 times since 2026-06-30 without execution — possible blocker or low priority
+────────────────────────────────────────────────────────────────
+
+<!-- assess:action=PARK -->
+```
 
 ## Notes
 
@@ -692,4 +789,5 @@ If confirmed, post a structured comment to each issue via `gh issue comment`. Ea
 - [ ] Supersession header prepended when prior assess comments exist (`buildSupersessionHeader`)
 - [ ] Churn warning included in dashboard when `detectChurn(...).isChurn === true`
 - [ ] Batch mode: table is the primary output, no per-issue detail sections
+- [ ] Persist step: each posted comment uses the single-mode verdict template (not the dashboard shape or a thinner form), with per-issue `⚠` carried into the warning slot and the 3-line marker block
 - [ ] Single mode: focused summary with separators between sections

package/templates/skills/assess/references/predicted-collision-detection.md

@@ -15,9 +15,12 @@ The detector runs automatically during Step 5 whenever ≥2 PROCEED issues are p
 
 For each issue body, paths are extracted in this order:
 
-### 1. Strip code blocks and HTML comments
+### 1. Strip code blocks, HTML comments, and background sections
 
-Fenced code blocks (```` ``` … ``` ````) and HTML comments (`<!-- … -->`) are removed before any path matching. This is the **AC-5 false-positive guard**: paths quoted as code in prose count, paths inside a code block don't.
+Two pre-extraction strips run before any path matching:
+
+- **Code blocks and HTML comments.** Fenced code blocks (```` ``` … ``` ````) and HTML comments (`<!-- … -->`) are removed. This is the **AC-5 false-positive guard**: paths quoted as code in prose count, paths inside a code block don't.
+- **Background/citation sections (#769).** Content under any H1/H2 heading whose text prefix-matches `BACKGROUND_SECTIONS` — `References`, `Context`, `Motivation`, `Additional context`, `See also` (case-insensitive) — is removed, up to the next H1/H2 heading. A path named *only* under such a section is a citation of existing code, not a file the issue will modify, so it no longer contributes to the path set. A path named in an AC bullet (or any other foreground section) survives even when it is *also* cited under `## References`.
 
 ### 2. Backtick-quoted source paths (PATH_REGEX)
 
@@ -85,9 +88,9 @@ These paths are stripped from every issue's path set before pairwise intersectio
 
 `EXCLUDED_PATHS` in `src/lib/assess-collision-detect.ts` is the canonical list. To add or remove an entry, edit that constant; this document and the skill prose pick up the change automatically.
 
-### Code block / HTML comment stripping
+### Code block / HTML comment / background-section stripping
 
-Step 1 of the extraction (above) removes all fenced code blocks and HTML comments before path matching. A path mentioned **only** inside one of those will not contribute to the issue's path set.
+Step 1 of the extraction (above) removes all fenced code blocks, HTML comments, and background/citation sections (`## References`, `## Context`, `## Motivation`, `## Additional context`, `## See also`) before path matching. A path mentioned **only** inside one of those will not contribute to the issue's path set. This is what stops sibling issues that all cite the same background doc under `## References` from being reported as a phantom collision (#769).
 
 ### Path-shape constraints
 
@@ -95,7 +98,7 @@ The PATH_REGEX requires a directory prefix (one of the six tracked roots) and a
 
 ## Tuning notes
 
-- **Proximity weighting** is not implemented. The original feature design proposed weighting paths inside `- [ ] **AC-N:**` bullets higher than paths in "Motivation" or "Additional context". Adding it is a follow-up if the false-positive rate becomes a problem in practice; leave it out until evidence demands it.
+- **Background-section exclusion is implemented (#769); proximity *scoring* is not.** The original design (#556) proposed weighting paths by proximity to `- [ ] **AC-N:**` bullets. #769 shipped the cheap version of that mitigation instead — strip whole background sections (`BACKGROUND_SECTIONS`: `References`, `Context`, `Motivation`, `Additional context`, `See also`) before extraction, so a path cited *only* as background drops out while AC-bullet paths survive. The fuller per-path scoring model remains a follow-up if wholesale section exclusion proves too blunt (e.g. a real target named only under `## Context` becomes a false negative); leave it out until evidence demands it.
 - **Cost.** For 13 issues (the realistic batch ceiling), pairwise comparison is 78 pairs — cheap, no real performance concern. Don't optimize prematurely.
 
 ## Output rules
@@ -104,6 +107,6 @@ The detector returns `CollisionResult[]` from `detectFileCollisions`. The format
 
 - `Order: A → B (path)` per pair (or `Order: A → B → C (path)` for 3+ on the same file). `path` is the canonical bare form (e.g. `qa/SKILL.md`).
 - `⚠ #N  Modifies <path> (overlaps #M); land sequentially` per affected issue.
-- `Chain: npx sequant run A B C --chain --qa-gate -Q   # alternative — N issues modify <path> (chain length≥3 historically 1/6 = 17%; see docs/reference/chain-mode-analysis-2026-05.md)` only when ≥3 issues collide on the same file (suggest-only). The historical-rate annotation comes from the #604 forensic write-up; users see the suggestion alongside the parallel default and can weigh the trade-off.
+- `Chain: npx sequant run A B C --chain -Q   # alternative — N issues modify <path> (chain length≥3 historically 1/6 = 17%, predates the #748/#749 fixes; see docs/reference/chain-mode-analysis-2026-05.md)` only when ≥3 issues collide on the same file (suggest-only). The historical-rate annotation comes from the #604 forensic write-up; users see the suggestion alongside the parallel default and can weigh the trade-off.
 
 The bare-filename `Order:` exception (defined in the skill's "Annotation Rules") applies here — predicted collisions are file-collision reasons by definition, so the filename in parentheses is the reason verbatim.

package/templates/skills/exec/SKILL.md

@@ -1657,6 +1657,35 @@ Parse the agent's output text for these patterns to detect failures:
 | `blocked by hook` | Operation was blocked by pre-tool hook |
 | `I'm unable to` | Agent hit a blocking constraint |
 
+### 4b2. Detecting Turn-Capped Implementers (Incomplete, not Failed)
+
+Every spawned implementer runs under a `maxTurns` cap (live since #484). Hitting the cap is **not** a failure — the agent did real, partial work before running out of turns, and that work is preserved (driver returns it flagged `capped: true` and warns rather than erroring, #733). Treat a capped implementer as **incomplete**, distinct from the hook-block failures in Section 4b.
+
+**Turn-cap detection keywords** (parse the agent's output text):
+
+| Pattern | Meaning |
+|---------|---------|
+| `error_max_turns` | Agent hit its turn cap |
+| `turn cap` / `Returning partial results` | Driver-emitted turn-cap warning |
+| Output ends mid-task with no completion report | Likely capped |
+
+**How to handle a capped implementer:**
+
+- Do **not** discard its changes or roll back the group — keep the partial work it committed.
+- Record, per task, **which tasks finished vs. which were capped**. A capped task is incomplete, not done.
+- Continue with the remaining (non-capped) tasks normally; one cap does not abort the whole `/exec` run.
+- The next `/exec` iteration (or a resumed session) picks up the capped task to finish it — note it explicitly so it is not mistaken for complete.
+- Reflect capped tasks honestly in the AC verification table (⚠️ Partial) and the progress update, rather than reporting the AC as fully satisfied.
+
+```markdown
+### Parallel Group Results
+
+| Task | Status |
+|------|--------|
+| Create types/metrics.ts | ✅ Finished |
+| Refactor batch-executor | ⚠️ Capped (incomplete — resume next iteration) |
+```
+
 ### 4c. Prompt Templates for Sub-Agents
 
 When spawning sub-agents for implementation tasks, use task-specific prompt templates for better results. See [prompt-templates.md](../_shared/references/prompt-templates.md) for the full reference.

package/templates/skills/fullsolve/SKILL.md

@@ -855,7 +855,7 @@ export CLAUDE_HOOKS_SMART_TESTS=true
 When enabled, smart tests will:
 - Auto-run related tests after each file edit during Phase 2 (EXEC)
 - Catch regressions immediately instead of waiting for explicit `npm test`
-- Log results to `/tmp/claude-tests.log` for debugging
+- Log results to `claude-tests.log` for debugging (`/logs/`, else `/.sequant/logs/`)
 
 **Benefits:**
 - Faster feedback loop during implementation

package/templates/skills/loop/SKILL.md

@@ -42,6 +42,30 @@ When invoked as `/loop <issue-number>`, your job is to:
 4. Re-run validation until quality gates pass
 5. Exit when `READY_FOR_MERGE` or max iterations reached
 
+## Orchestration Context
+
+When running as part of an orchestrated workflow (e.g., `sequant run` or `/fullsolve`), this skill receives environment variables that indicate the orchestration context:
+
+| Environment Variable | Description | Example Value |
+|---------------------|-------------|---------------|
+| `SEQUANT_ORCHESTRATOR` | The orchestrator invoking this skill | `sequant-run` |
+| `SEQUANT_PHASE` | Current phase in the workflow | `loop` |
+| `SEQUANT_ISSUE` | Issue number being processed | `123` |
+| `SEQUANT_WORKTREE` | Path to the feature worktree | `/path/to/worktrees/feature/...` |
+
+**Behavior when orchestrated (SEQUANT_ORCHESTRATOR is set):**
+
+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
+
+**Behavior when standalone (SEQUANT_ORCHESTRATOR is NOT set):**
+
+- Locate worktree from issue number
+- Post progress comments to GitHub
+- Fetch issue context if needed
+
 ## Invocation
 
 - `/loop 123` - Parse log for issue #123, fix issues, re-validate
@@ -50,12 +74,66 @@ When invoked as `/loop <issue-number>`, your job is to:
 
 ### Step 1: Read Previous Phase Output
 
+**The source of findings depends on whether you're running in orchestrated or standalone mode.**
+
+#### 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:
+
+```bash
+# Check if we're in orchestrated mode
+if [[ -n "$SEQUANT_ORCHESTRATOR" ]]; then
+  echo "Orchestrated mode detected (orchestrator: $SEQUANT_ORCHESTRATOR)"
+
+  # Use SEQUANT_ISSUE if provided, otherwise parse from invocation
+  ISSUE_NUMBER="${SEQUANT_ISSUE:-<issue-number>}"
+
+  # Fetch QA findings from issue comments (use startswith to avoid matching comments that reference QA format)
+  gh issue view "$ISSUE_NUMBER" --json comments -q '.comments[] | select(.body | startswith("## QA Review for Issue")) | .body' | tail -1
+fi
+```
+
+**How to identify QA comments:**
+
+| Pattern | Meaning |
+|---------|---------|
+| `## 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 |
+
+**Parsing QA comment:**
+```bash
+# Extract verdict from QA comment
+verdict=$(echo "$qa_comment" | grep -oE "Verdict:\s*\w+" | head -1 | awk '{print $2}' || true)
+
+# 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)
+```
+
+**If no QA comment found in orchestrated mode:**
+1. Log a clear error: `"Warning: No QA comment found in 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
+
+#### Step 1B: Standalone Mode (no SEQUANT_ORCHESTRATOR)
+
+When running standalone (interactive `/loop` invocation), read from the log file:
+
 Use the Read tool to read the log file for this issue:
 ```
 Read(file_path="/tmp/claude-issue-<issue-number>.log")
 ```
 
-Parse the log to find:
+**If log file doesn't exist:**
+- Error: `"Log file not found at /tmp/claude-issue-<N>.log. Please run /spec, /exec, /test, or /qa first."`
+
+#### Parsing Findings (Both Modes)
+
+Parse the output (from comment or log file) to find:
 - **Last phase executed:** `/test` or `/qa`
 - **Verdict:** `READY_FOR_MERGE`, `AC_MET_BUT_NOT_A_PLUS`, `NEEDS_VERIFICATION`,
   or `AC_NOT_MET`
@@ -102,6 +180,12 @@ Extract:
 
 ### 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:**
+
 Find the worktree for this issue:
 ```bash
 git worktree list | grep -E "feature.*<issue-number>" || true
@@ -365,7 +449,21 @@ For each iteration, output:
 
 ## Error Handling
 
-**If log file doesn't exist:**
+**If orchestrated but no QA comment found:**
+```
+Warning: No QA comment found in issue #<N>
+Attempting fallback to log file...
+```
+
+If fallback also fails:
+```
+Error: No QA findings available.
+- No QA comment found in issue #<N>
+- Log file not found at /tmp/claude-issue-<N>.log
+Please run /qa <N> first.
+```
+
+**If log file doesn't exist (standalone mode):**
 ```
 Error: Log file not found at /tmp/claude-issue-<N>.log
 Please run /spec, /exec, /test, or /qa first.