sequant 2.6.2 → 2.8.0

package/.claude-plugin/marketplace.json

@@ -8,7 +8,7 @@
     {
       "name": "sequant",
       "description": "AI coding agent orchestrator for Claude Code — resolve GitHub issues end-to-end with isolated git worktrees, quality gates, and an MCP server. Includes 17 skills, workflow MCP tools, and pre/post-tool hooks.",
-      "version": "2.6.2",
+      "version": "2.8.0",
       "author": {
         "name": "sequant-io",
         "email": "hello@sequant.io"

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "sequant",
   "description": "AI coding agent orchestrator for Claude Code — resolve GitHub issues end-to-end with isolated git worktrees and quality gates, through spec → exec → qa phases.",
-  "version": "2.6.2",
+  "version": "2.8.0",
   "author": {
     "name": "sequant-io",
     "email": "hello@sequant.io"

package/README.md

@@ -16,6 +16,16 @@ AI coding agents write code well, but leave you to run the workflow around it
 
 See the [CHANGELOG](CHANGELOG.md) for release notes, or the [migration guide](CHANGELOG.md#migration-from-v1x) if upgrading from v1.x.
 
+### What's new in 2.8
+
+- **Clearer failures when an agent stops early** — phases that hit a turn cap now preserve their partial work and halt cleanly for resume instead of discarding it (#739, #733), and rate-limit/out-of-credits failures are named for what they are (with reset time and credit-purchase hints) rather than buried under generic retry noise (#732).
+- **Runtime Node-version guard** — `sequant` checks the running Node against its `engines.node` floor (`>=22.12.0`) at startup and exits with a friendly upgrade message instead of crashing later on a Node-22-only API (#734).
+- **`/assess` avoids npx version skew** — it now emits `sequant run …` when a global install is on `PATH` (and the unchanged `npx sequant run …` otherwise), so copy-pasted commands don't silently run a stale binary (#740).
+
+### What's new in 2.7
+
+- **Trustworthy `--dry-run` previews for `sync` and `update`** — `sequant sync --dry-run` (`-d`) previews the exact set the apply would write (`new` + `modified` + `local-override`) and mutates nothing. Both `sync --dry-run` and `update --dry-run` now exit non-zero when work is pending, so a CI/automation job can gate on the exit code instead of parsing stdout. (`update` is the interactive command; `sync` is the documented non-interactive/CI surface.)
+
 ### What's new in 2.6
 
 - **Boxed Ink TUI is the default for `sequant run`** — on a TTY, `run` now renders the boxed dashboard by default (matching `sequant ready`). Opt out with `--no-tui` (line renderer) or `-s`/`--quiet` (heartbeat-only); non-TTY output auto-degrades.
@@ -95,7 +105,9 @@ SEQUANT WORKFLOW · #683
 
 QA findings post back to the issue as comments, with each acceptance criterion re-checked independently.
 
-> 📹 A recorded demo GIF of the live run grid is coming — tracked in [#695](https://github.com/sequant-io/sequant/issues/695).
+<p align="center">
+  <img src="https://raw.githubusercontent.com/sequant-io/sequant/main/docs/assets/run-grid.gif" alt="Sequant run grid: the live boxed TUI driving issue #64 through spec, exec, and qa to a green success rollup" width="760">
+</p>
 
 ---
 

package/dist/bin/cli.d.ts

@@ -4,4 +4,4 @@
  *
  * Sequential AI phases with quality gates for any codebase.
  */
-export {};
+import "./preflight.js";

package/dist/bin/cli.js

@@ -4,6 +4,12 @@
  *
  * Sequential AI phases with quality gates for any codebase.
  */
+// MUST stay first (#734): the Node-version preflight guard. ESM evaluates a
+// module's imports depth-first in source order before the importer's body, so
+// this side-effecting import runs the guard before commander / chalk / the
+// agent SDK / command modules are evaluated — closing the import-time crash
+// window on an old Node below the engines floor. See bin/preflight.ts.
+import "./preflight.js";
 import { Command, InvalidArgumentError, Option } from "commander";
 import chalk from "chalk";
 import { fileURLToPath } from "url";
@@ -15,7 +21,9 @@ import { configureUI, banner } from "../src/lib/cli-ui.js";
 import { isCI, isStdoutTTY } from "../src/lib/tty.js";
 import { detectPackageManagerSync, getPackageManagerCommands, } from "../src/lib/stacks.js";
 // Read version from package.json dynamically
-// Works from both source (bin/) and compiled (dist/bin/) locations
+// Works from both source (bin/) and compiled (dist/bin/) locations.
+// Note: the engines.node floor is read separately in bin/preflight.ts, which
+// must run before this module's imports — see the side-effecting import above.
 function getVersion() {
     const __dirname = dirname(fileURLToPath(import.meta.url));
     let dir = __dirname;
@@ -88,6 +96,7 @@ configureUI({
     isCI: isCI(),
     minimal: process.env.SEQUANT_MINIMAL === "1",
 });
+// (Node-version preflight guard runs at import time — see bin/preflight.ts.)
 // Warn if running from a problematic install location.
 // The home-stray case ($HOME/node_modules/sequant) gets a distinct warning
 // because it pollutes resolution for every subdirectory of $HOME, which the
@@ -135,6 +144,7 @@ program
     .description("Sync skills and templates from the Sequant package (non-interactive)")
     .option("-f, --force", "Sync even if versions match")
     .option("-q, --quiet", "Suppress output")
+    .option("-d, --dry-run", "Show what sync would write without making changes (exits non-zero if work is pending)")
     .action(syncCommand);
 program
     .command("doctor")

package/dist/bin/preflight.d.ts

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+/**
+ * Runtime Node-version preflight (#734).
+ *
+ * This module is imported FIRST in `bin/cli.ts`, ahead of every third-party
+ * import (commander, chalk, the agent SDK) and every command module. ESM
+ * evaluates a module's dependencies depth-first in source order before the
+ * importer's body runs, so this module's top-level guard executes before any
+ * of those heavier modules are evaluated. That closes the import-time crash
+ * window: if a dependency tripped a Node-22-only API at module-load time on an
+ * old Node, the user would otherwise get an opaque stack trace from the import
+ * itself — before the in-body guard at `cli.ts` ever ran.
+ *
+ * The only modules evaluated before this guard are Node built-ins plus the
+ * first-party `version-check.ts` chain (→ `stacks.ts` → `fs.ts`), which import
+ * built-ins only and are therefore safe on the old Node this guard rejects.
+ *
+ * The pure comparison logic lives in `src/lib/version-check.ts` (AC-6); this
+ * file is just the early entry point that reads the floor and invokes it.
+ */
+export {};

package/dist/bin/preflight.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+/**
+ * Runtime Node-version preflight (#734).
+ *
+ * This module is imported FIRST in `bin/cli.ts`, ahead of every third-party
+ * import (commander, chalk, the agent SDK) and every command module. ESM
+ * evaluates a module's dependencies depth-first in source order before the
+ * importer's body runs, so this module's top-level guard executes before any
+ * of those heavier modules are evaluated. That closes the import-time crash
+ * window: if a dependency tripped a Node-22-only API at module-load time on an
+ * old Node, the user would otherwise get an opaque stack trace from the import
+ * itself — before the in-body guard at `cli.ts` ever ran.
+ *
+ * The only modules evaluated before this guard are Node built-ins plus the
+ * first-party `version-check.ts` chain (→ `stacks.ts` → `fs.ts`), which import
+ * built-ins only and are therefore safe on the old Node this guard rejects.
+ *
+ * The pure comparison logic lives in `src/lib/version-check.ts` (AC-6); this
+ * file is just the early entry point that reads the floor and invokes it.
+ */
+import { readFileSync } from "fs";
+import { fileURLToPath } from "url";
+import { dirname, resolve } from "path";
+import { assertNodeVersion } from "../src/lib/version-check.js";
+// Derive the engines floor from package.json (single source of truth, AC-3),
+// using the same walk-up read as getVersion() in cli.ts. Built-in globals only,
+// so this runs — rather than crashes — on the old Node it is meant to reject.
+function readEngineFloor() {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    while (dir !== dirname(dir)) {
+        const candidate = resolve(dir, "package.json");
+        try {
+            const pkg = JSON.parse(readFileSync(candidate, "utf-8"));
+            if (pkg.name === "sequant") {
+                return pkg.engines?.node ?? null;
+            }
+        }
+        catch {
+            // Not found at this level, keep walking up.
+        }
+        dir = dirname(dir);
+    }
+    return null; // Fallback — assertNodeVersion treats a null floor as "skip".
+}
+assertNodeVersion(readEngineFloor());

package/dist/marketplace/external_plugins/sequant/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "sequant",
   "description": "AI coding agent orchestrator for Claude Code — resolve GitHub issues end-to-end with isolated git worktrees and quality gates, through spec → exec → qa phases.",
-  "version": "2.6.2",
+  "version": "2.8.0",
   "author": {
     "name": "sequant-io",
     "email": "hello@sequant.io"

package/dist/marketplace/external_plugins/sequant/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/dist/marketplace/external_plugins/sequant/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,7 +196,7 @@ 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 --qa-gate -Q <phases>   # alternative — <one-line reason>` (`<CMD_PREFIX>` resolved in Step 1)
 
 Flag references:
 - `--chain` chains issues (each branches from previous; implies `--sequential`)
@@ -233,15 +247,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 --qa-gate -Q <phases>   # alternative — <reason>
 
 Flags:
   <flag>                <one-line reason>
@@ -286,6 +300,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 +318,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 --qa-gate -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 +336,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              ‖
@@ -485,7 +502,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 +634,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
 ────────────────────────────────────────────────────────────────

package/dist/marketplace/external_plugins/sequant/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/dist/marketplace/external_plugins/sequant/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.

package/dist/marketplace/external_plugins/sequant/skills/qa/SKILL.md

@@ -1085,6 +1085,30 @@ skill_modified=$(git diff main...HEAD --name-only | grep -E "^\.(claude/skills|s
 ```
 If skill files are modified, the quality-checks.sh script automatically runs the three-directory sync check (section 12). If divergence is detected, this blocks `READY_FOR_MERGE` — verdict becomes `AC_MET_BUT_NOT_A_PLUS` with a note to run `npx tsx scripts/check-skill-sync.ts --fix`.
 
+#### Turn-Capped Checks → Inconclusive (not a phase failure)
+
+A spawned quality-check sub-agent runs under a `maxTurns` cap (live on every agent since #484). When an agent hits that cap, its work is **partial**, not failed — the driver returns it flagged `capped: true` and warns rather than erroring (#733).
+
+**How to recognize a turn-capped check:** the sub-agent's reported output is truncated mid-analysis, ends without a verdict, or explicitly notes it ran out of turns (look for `error_max_turns`, "turn cap", or "Returning partial results" in its output).
+
+**How to handle it — do NOT fail the whole QA phase on a cap alone:**
+
+- Mark that single check **⚠️ Inconclusive** in the QA summary, with a one-line reason (`hit turn cap — partial analysis`).
+- Use whatever partial findings the capped agent *did* surface; do not discard them.
+- Let the **other** checks proceed and contribute to the verdict normally.
+- If a capped check leaves an AC genuinely unverified, the verdict is `NEEDS_VERIFICATION` for that AC — never a hard `AC_NOT_MET` justified solely by the cap.
+- Surface inconclusive checks prominently so a human can re-run that check (e.g. with a higher cap) rather than silently treating the cap as a pass.
+
+```markdown
+### Quality Checks
+
+| Check | Status | Notes |
+|-------|--------|-------|
+| Type safety | ✅ Pass | 0 issues |
+| Scope/size | ⚠️ Inconclusive | hit turn cap — partial analysis, re-run recommended |
+| Security | ✅ Pass | 0 critical |
+```
+
 See [quality-gates.md](references/quality-gates.md) for detailed verdict synthesis.
 
 ### Using MCP Tools (Optional)