sequant 2.4.0 → 2.5.0

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

@@ -22,14 +22,21 @@ allowed-tools:
   - Bash(gh issue comment:*)
   - Bash(gh issue edit:*)
   - Bash(gh pr create:*)
+  - Bash(gh pr list:*)
+  - Bash(gh pr merge:*)
   - Bash(npm test:*)
   - Bash(npm run build:*)
   - Bash(git diff:*)
   - Bash(git status:*)
+  - Bash(git log:*)
   - Bash(git add:*)
   - Bash(git commit:*)
   - Bash(git push:*)
   - Bash(git worktree:*)
+  - Bash(./scripts/dev/*:*)
+  - Bash(./scripts/cleanup-worktree.sh:*)
+  - Bash(./scripts/new-feature.sh:*)
+  - Bash(./scripts/list-worktrees.sh:*)
 ---
 
 # Full Solve Command
@@ -40,6 +47,26 @@ You are the "Full Solve Agent" for the current repository.
 
 When invoked as `/fullsolve <issue-number>`, execute the complete issue resolution workflow with integrated quality loops. This command orchestrates all phases and automatically iterates until quality gates pass.
 
+## CRITICAL: Auto-Progression Between Phases
+
+**DO NOT wait for user confirmation between phases.** This is an autonomous workflow.
+
+After each phase completes successfully, **immediately proceed** to the next phase:
+1. `/spec` completes → **immediately** invoke `/exec`
+2. `/exec` completes → **immediately** invoke `/test` (if UI) or `/qa`
+3. `/test` completes → **immediately** invoke `/qa`
+4. `/qa` completes → **immediately** create PR
+
+**The user invoked `/fullsolve` expecting end-to-end automation.** Only stop for:
+- Unrecoverable errors (after retry attempts exhausted)
+- Final summary after PR creation
+- Explicit user interruption
+
+```
+WRONG: "Spec complete. Ready for exec phase." [waits]
+RIGHT: "Spec complete. Proceeding to exec..." [invokes /exec immediately]
+```
+
 ## Workflow Overview
 
 ```
@@ -88,8 +115,59 @@ When invoked as `/fullsolve <issue-number>`, execute the complete issue resoluti
 /fullsolve 218                    # Standard full solve
 /fullsolve 218 --skip-test        # Skip testing phase (backend issues)
 /fullsolve 218 --max-iterations 5 # Override max fix iterations
+/fullsolve 218 --parallel         # Force parallel agent execution (faster, higher token usage)
+/fullsolve 218 --sequential       # Force sequential agent execution (slower, lower token usage)
 ```
 
+## Agent Execution Mode
+
+When spawning sub-agents for quality checks, determine the execution mode:
+
+1. **Check for CLI flag override:**
+   - `--parallel` → Run sub-agents in parallel
+   - `--sequential` → Run sub-agents one at a time
+
+2. **If no flag, read project settings:**
+   Use the Read tool to check project settings:
+   ```
+   Read(file_path=".sequant/settings.json")
+   # Parse JSON and extract agents.parallel (default: false)
+   ```
+
+3. **Default:** Sequential (cost-optimized)
+
+| Mode | Token Usage | Speed | Best For |
+|------|-------------|-------|----------|
+| Sequential | 1x (baseline) | Slower | Limited API plans, single issues |
+| Parallel | ~2-3x | ~50% faster | Unlimited plans, batch operations |
+
+**Pass execution mode to child skills:** When invoking `/qa` or other skills that spawn agents, pass the `--parallel` or `--sequential` flag to maintain consistency.
+
+## Orchestration Context
+
+This skill acts as an **orchestrator** and sets environment variables for child skills to optimize their behavior:
+
+| Environment Variable | Description | Example Value |
+|---------------------|-------------|---------------|
+| `SEQUANT_ORCHESTRATOR` | Identifies the orchestrator | `sequant-run` |
+| `SEQUANT_PHASE` | Current phase being executed | `spec`, `exec`, `test`, `qa`, `loop` |
+| `SEQUANT_ISSUE` | Issue number being processed | `218` |
+| `SEQUANT_WORKTREE` | Path to the feature worktree | `/path/to/worktrees/feature/218-...` |
+
+**Benefits of orchestration context:**
+
+1. **Faster execution** - Child skills skip redundant pre-flight checks
+2. **Cleaner GitHub comments** - Only orchestrator posts progress updates
+3. **Better coordination** - Skills can trust worktree and issue context
+4. **Reduced API calls** - Issue fetch happens once, not per-phase
+
+**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
+- `/test`: Skips issue fetch, trusts orchestrator context
+- `/qa`: Skips pre-flight sync, defers GitHub updates
+- `/loop`: Uses provided worktree, defers GitHub updates
+
 ## Phase Detection (Smart Resumption)
 
 **Before starting any phase**, detect the current workflow state from GitHub issue comments to enable smart resumption:
@@ -169,144 +247,189 @@ 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).
 
-## Phase 1: Planning (SPEC)
-
-Execute the planning phase inline (not as separate command):
+### 0.3 Acquire Concurrency Lock (#625)
 
-### 1.1 Fetch Issue Context
+**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.
 
 ```bash
-gh issue view <issue-number> --json title,body,labels
-gh issue view <issue-number> --comments
+# Acquire lock for this issue. --skip-pid-check is required: the shell that
+# runs this command exits immediately, so the lock's PID is dead by the time
+# the next check runs. Stale recovery falls back to age-only (2h).
+if ! npx sequant locks acquire <issue-number> \
+    --command="/fullsolve <issue-number>" \
+    --skip-pid-check; then
+  echo "❌ Another session is working on #<issue-number>. Run 'npx sequant locks list' for details."
+  echo "   If you're sure the holder is dead, run: npx sequant locks clear <issue-number>"
+  exit 1
+fi
 ```
 
-### 1.2 Extract Acceptance Criteria
+**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.
+
+**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>`.
 
-Parse issue body and comments to build AC checklist:
-- AC-1, AC-2, etc.
-- Identify blockers, dependencies
-- Note open questions
+**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.
 
-### 1.3 Create Implementation Plan
+## Phase 1: Planning (SPEC)
 
-- Break down into 3-7 implementation steps
-- Identify complexity and risks
-- Post plan comment to issue
+**Invoke the `/spec` skill** to plan implementation and extract acceptance criteria.
 
-**Use Sequential Thinking for Complex Planning:**
+### 1.1 Invoke Spec Skill
 
-If the issue involves architectural decisions or multiple valid approaches, use Sequential Thinking MCP:
+Use the `Skill` tool to invoke `/spec`:
 
-```javascript
-// For complex issues with multiple implementation paths
-mcp__sequential-thinking__sequentialthinking({
-  thought: "Analyzing implementation approaches for [feature]. Options: 1) [Approach A] - pros/cons. 2) [Approach B] - pros/cons. 3) [Approach C] - pros/cons...",
-  thoughtNumber: 1,
-  totalThoughts: 4,
-  nextThoughtNeeded: true
-})
 ```
+Skill(skill: "spec", args: "<issue-number>")
+```
+
+The `/spec` skill will:
+- Fetch issue context from GitHub
+- Extract acceptance criteria (AC-1, AC-2, etc.)
+- Create implementation plan (3-7 steps)
+- Post plan comment to the issue
+- Create feature worktree
+
+### 1.2 Capture Spec Output
 
-**When to use Sequential Thinking in planning:**
-- Issue labeled `complex`, `refactor`, or `architecture`
-- 3+ valid implementation approaches exist
-- Unclear trade-offs between options
-- Previous implementation attempt failed
+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)
 
-**Fallback:** If Sequential Thinking unavailable, document pros/cons explicitly in the plan comment.
+```markdown
+## Spec Output Captured
+
+**Issue:** #<N>
+**Worktree:** ../worktrees/feature/<issue-number>-*/
+**AC Count:** <N> items
+**Needs Testing:** Yes/No (based on labels)
+```
 
-### 1.4 Create Feature Worktree
+### 1.3 Handle Spec Failures
+
+If `/spec` fails:
+- Check if issue exists and is readable
+- Verify GitHub CLI authentication
+- **Release the lock acquired in Phase 0.3** (so the user can retry without hitting the orphan window)
+- Report failure and exit workflow
 
 ```bash
-./scripts/dev/new-feature.sh <issue-number>
+# Release before halting — see Phase 0.3 release contract.
+npx sequant locks release <issue-number> || true
+```
+
+```markdown
+## Spec Failed
+
+**Error:** [error message]
+**Action Required:** [what the user needs to do]
+
+Workflow halted. Fix the issue and re-run `/fullsolve <issue-number>`.
 ```
 
 **State after Phase 1:**
 - AC checklist defined
-- Implementation plan created
+- Implementation plan created (and posted to GitHub)
 - Feature worktree ready
 
+**→ IMMEDIATELY proceed to Phase 2 (do not wait for user input)**
+
 ## Phase 2: Implementation (EXEC)
 
-### 2.1 Navigate to Worktree
+**Invoke the `/exec` skill** to implement all acceptance criteria.
 
-```bash
-cd ../worktrees/feature/<issue-number>-*/
+### 2.1 Invoke Exec Skill
+
+Use the `Skill` tool to invoke `/exec`:
+
+```
+Skill(skill: "exec", args: "<issue-number>")
 ```
 
-### 2.2 MCP Availability Check (Optional Enhancement)
+The `/exec` skill will:
+- Navigate to the feature worktree
+- Implement each AC item
+- Run tests and build after changes
+- Verify quality gates pass
 
-Before implementation, check MCP tool availability for enhanced workflow:
+### 2.2 Pass Orchestration Context
 
-```markdown
-**Available MCPs:**
-- [ ] Context7 (`mcp__context7__*`) - For external library documentation
-- [ ] Sequential Thinking (`mcp__sequential-thinking__*`) - For complex decisions
-- [ ] Chrome DevTools (`mcp__chrome-devtools__*`) - For browser testing in Phase 3
-```
+Set environment variables before invoking `/exec` so it can optimize its behavior:
 
-**If MCPs unavailable:** Continue with standard implementation - fallback strategies documented in `/exec` skill.
+```bash
+export SEQUANT_ORCHESTRATOR=fullsolve
+export SEQUANT_PHASE=exec
+export SEQUANT_ISSUE=<issue-number>
+export SEQUANT_WORKTREE=../worktrees/feature/<issue-number>-*/
+```
 
-### 2.3 Implement Each AC Item
+When `/exec` detects `SEQUANT_ORCHESTRATOR`, it:
+- Skips worktree creation (already done by `/spec`)
+- Uses the provided worktree path
+- Defers GitHub comment updates to orchestrator
 
-For each AC item:
-1. Understand requirement
-2. Find similar patterns in codebase (use Glob/Grep first)
-3. **If using unfamiliar library:** Use Context7 for documentation lookup
-4. **If facing complex decision:** Use Sequential Thinking to analyze approaches
-5. Implement minimal solution
-6. Run tests and build
-7. Mark AC as complete
+### 2.3 Handle Exec Failures
 
-**MCP Usage in Implementation Loop:**
+If `/exec` fails (tests or build):
 
+**Attempt fix (max 3 iterations):**
 ```
-For each AC item:
-│
-├─ Need external library API? → Use Context7 (if available)
-│   └─ Fallback: WebSearch for documentation
-│
-├─ Multiple valid approaches? → Use Sequential Thinking (if available)
-│   └─ Fallback: Explicit pros/cons analysis in response
-│
-└─ Standard implementation → Use Glob/Grep for patterns
-```
+exec_iteration = 0
+while exec_iteration < MAX_EXEC_ITERATIONS:
+    result = Skill(skill: "exec", args: "<issue-number>")
 
-### 2.4 Quality Gates
+    if result.success:
+        break
 
-After implementation:
-- `npm test` - All tests pass
-- `npm run build` - Build succeeds
-- `git diff` - Changes are proportional
+    # Parse and log failure
+    log_failure(result.error)
+    exec_iteration += 1
+```
 
-### 2.5 Final Verification (CRITICAL)
+**If all iterations exhausted:**
+```bash
+# Release before halting — see Phase 0.3 release contract.
+npx sequant locks release <issue-number> || true
+```
 
-**After ALL implementation changes are complete**, run verification one more time:
+```markdown
+## Exec Failed
 
-```bash
-# Run full test suite AFTER all changes
-npm test
+**Iterations:** 3/3 exhausted
+**Last Error:** [error message]
 
-# Verify build still works
-npm run build
+Workflow halted. Manual intervention required.
 ```
 
-**Why this matters:** Tests run during implementation may pass before file conversions or final changes are made. Always verify after the LAST change, not just after each intermediate step.
+### 2.4 Capture Exec Output
 
-**If tests fail at this stage:**
-1. Fix the failing tests (update paths, content checks, etc.)
-2. Re-run `npm test` until all pass
-3. Do NOT proceed to Phase 3 until tests pass
+After successful `/exec`:
+- Verify tests passed
+- Verify build succeeded
+- Record files changed
+
+```markdown
+## Exec Complete
+
+**Tests:** ✅ All passing
+**Build:** ✅ Succeeded
+**Files Changed:** <N>
+```
 
 **State after Phase 2:**
 - All AC items implemented
 - Tests passing (verified AFTER final changes)
 - Build succeeding
 
+**→ IMMEDIATELY proceed to Phase 3 or 4 (do not wait for user input)**
+- If UI labels (`ui`, `frontend`, `admin`) present AND no `no-browser-test` label → invoke `/test`
+- If `no-browser-test` label present → skip to `/qa` (explicit opt-out)
+- Otherwise → skip to `/qa`
+
 ## Phase 3: Testing (TEST)
 
 **Skip if:**
-- Issue doesn't have `admin`, `ui`, or `frontend` labels, OR
+- Issue doesn't have `admin`, `ui`, or `frontend` labels (determined from `/spec` output), OR
 - Issue has `no-browser-test` label (explicit opt-out, overrides UI labels)
 
 ### Browser Testing Label Reference
@@ -317,105 +440,182 @@ npm run build
 | `no-browser-test` | Always skips `/test` phase (explicit opt-out) |
 | Neither | Auto-detection in `/spec` may suggest adding `ui` label |
 
-### 3.1 Start Dev Server
+**Invoke the `/test` skill** for browser-based UI testing.
 
-```bash
-npm run dev &
-```
+### 3.1 Invoke Test Skill
+
+Use the `Skill` tool to invoke `/test`:
 
-### 3.2 Execute Test Cases
+```
+Skill(skill: "test", args: "<issue-number>")
+```
 
-Using Chrome DevTools MCP:
-- Navigate to feature
+The `/test` skill will:
+- Start development server
+- Navigate to feature in browser (Chrome DevTools MCP)
 - Execute each test case
-- Record PASS/FAIL/BLOCKED
+- Record PASS/FAIL/BLOCKED results
+
+### 3.2 Pass Orchestration Context
+
+```bash
+export SEQUANT_ORCHESTRATOR=fullsolve
+export SEQUANT_PHASE=test
+export SEQUANT_ISSUE=<issue-number>
+export SEQUANT_WORKTREE=../worktrees/feature/<issue-number>-*/
+```
+
+When `/test` detects `SEQUANT_ORCHESTRATOR`, it:
+- Skips issue fetch (trusts orchestrator context)
+- Uses provided AC checklist
+- Defers GitHub updates to orchestrator
 
 ### 3.3 Test Loop (Max 3 iterations)
 
+If tests fail, invoke `/loop` to fix and re-test:
+
 ```
 test_iteration = 0
-while test_iteration < 3:
-    run_tests()
+while test_iteration < MAX_TEST_ITERATIONS:
+    result = Skill(skill: "test", args: "<issue-number>")
 
-    if all_tests_pass:
+    if result.all_tests_pass:
         break
 
-    # Parse failures
-    failed_tests = parse_failed_tests()
+    # Use /loop to fix failures
+    Skill(skill: "sequant:loop", args: "<issue-number> --phase test")
+    test_iteration += 1
+```
 
-    # Fix each failure
-    for test in failed_tests:
-        understand_failure()
-        implement_fix()
-        verify_fix()
+### 3.4 Handle Test Exhaustion
 
-    test_iteration += 1
+If max iterations reached:
+
+```markdown
+## Test Loop Exhausted
+
+**Iterations:** 3/3
+**Remaining Failures:** [list]
+
+Proceeding to QA phase. Failures will be documented.
 ```
 
 **State after Phase 3:**
 - All tests passing (or max iterations reached)
 - Bugs documented and fixed
 
+**→ IMMEDIATELY proceed to Phase 4 (do not wait for user input)**
+
 ## Phase 4: Quality Assurance (QA)
 
-### 4.1 Automated Quality Checks
+**Invoke the `/qa` skill** for code review and AC validation.
 
-```bash
-# Type safety
-git diff main...HEAD | grep -E ":\s*any[,)]|as any" || true
+### 4.1 Invoke QA Skill
 
-# Deleted tests
-git diff main...HEAD --diff-filter=D --name-only | grep -E "\.test\." || true
+Use the `Skill` tool to invoke `/qa`:
 
-# Scope check
-git diff main...HEAD --name-only | wc -l
-
-# Size check
-git diff main...HEAD --numstat
 ```
+Skill(skill: "qa", args: "<issue-number>")
+```
+
+The `/qa` skill will:
+- Run automated quality checks (type safety, deleted tests, scope)
+- Review AC coverage (MET/PARTIALLY_MET/NOT_MET/PENDING)
+- Generate review comment draft
+- Return verdict: READY_FOR_MERGE, AC_MET_BUT_NOT_A_PLUS, NEEDS_VERIFICATION,
+  or AC_NOT_MET
 
-### 4.2 AC Coverage Review
+### 4.2 Pass Orchestration Context
 
-For each AC item, mark:
-- `MET` - Fully implemented
-- `PARTIALLY_MET` - Needs more work
-- `NOT_MET` - Not implemented
+```bash
+export SEQUANT_ORCHESTRATOR=fullsolve
+export SEQUANT_PHASE=qa
+export SEQUANT_ISSUE=<issue-number>
+export SEQUANT_WORKTREE=../worktrees/feature/<issue-number>-*/
+```
+
+When `/qa` detects `SEQUANT_ORCHESTRATOR`, it:
+- Skips pre-flight sync
+- Defers GitHub comment posting to orchestrator
+- Returns structured verdict for orchestrator to process
 
 ### 4.3 QA Loop (Max 2 iterations)
 
+If verdict is not `READY_FOR_MERGE`, invoke `/loop` to fix and re-run QA.
+
+**Stagnation gate (issue #581):** Before each `/qa` re-invocation after iteration 1, run the stagnation detector. If it reports `stagnant: true` with reason `SAME_SHA_NO_PROGRESS`, the prior `/loop` made no commit and produced no diff — re-running `/qa` would yield the same verdict. Halt the loop and surface a hard blocker instead of wasting another cycle.
+
+```bash
+# Run before each /qa call after iteration 0 (skip on first call):
+npx tsx scripts/qa-stagnation.ts detect <issue-number>
+# Output (JSON): {"stagnant": true|false, "reason"?: "SAME_SHA_NO_PROGRESS", "message": "...", ...}
+# When stagnant === true: record telemetry, then halt — do NOT call /qa again.
+npx tsx scripts/qa-stagnation.ts record <issue-number> <iteration> SAME_SHA_NO_PROGRESS --verdict=AC_NOT_MET
 ```
-qa_iteration = 0
-while qa_iteration < 2:
-    run_qa_checks()
 
-    if verdict == "READY_FOR_MERGE":
+```
+qa_iteration = 0
+while qa_iteration < MAX_QA_ITERATIONS:
+    if qa_iteration > 0:
+        # Stagnation gate — same-SHA same-verdict cycles are wasted.
+        decision = `npx tsx scripts/qa-stagnation.ts detect <issue-number>`
+        if decision.stagnant == true:
+            `npx tsx scripts/qa-stagnation.ts record <issue-number> {qa_iteration} SAME_SHA_NO_PROGRESS --verdict=AC_NOT_MET`
+            # Halt — no progress since last QA. Skip to 4.4 with stagnation note.
+            break
+
+    result = Skill(skill: "qa", args: "<issue-number>")
+
+    if result.verdict == "READY_FOR_MERGE":
         break
 
-    if verdict == "AC_MET_BUT_NOT_A_PLUS":
+    if result.verdict == "AC_MET_BUT_NOT_A_PLUS":
         # Good enough, proceed with notes
         break
 
-    if verdict == "NEEDS_VERIFICATION":
+    if result.verdict == "NEEDS_VERIFICATION":
         # ACs are met but pending external verification
         # Proceed to PR - verification can happen post-PR
         break
 
-    # Parse issues (AC_NOT_MET)
-    issues = parse_qa_issues()
+    # Use /loop to fix issues (AC_NOT_MET)
+    Skill(skill: "sequant:loop", args: "<issue-number> --phase qa")
+    qa_iteration += 1
+```
 
-    # Fix each issue
-    for issue in issues:
-        understand_issue()
-        implement_fix()
-        verify_fix()
+### 4.4 Handle QA Exhaustion
 
-    qa_iteration += 1
+If max iterations reached with `AC_NOT_MET`:
+
+```markdown
+## QA Loop Exhausted
+
+**Iterations:** 2/2
+**Verdict:** AC_NOT_MET
+**Remaining Issues:** [list]
+
+Creating PR with notes for human review.
 ```
 
 **State after Phase 4:**
-- AC fully met
+- AC fully met (or documented as partial)
 - Code quality validated
-- Ready for merge
+- Ready for merge (or flagged for human review)
+
+**→ IMMEDIATELY proceed to Phase 5 after self-evaluation (do not wait for user input)**
+
+### 4.5 Risk Assessment
+
+Risk assessment is performed during the QA phase — see QA output above. If QA was skipped or incomplete, state risks here using the same format:
+
+```markdown
+### Risk Assessment
+
+- **Likely failure mode:** [How would this break in production?]
+- **Not tested:** [What gaps exist in test coverage?]
+```
+
+---
 
 ## Phase 5: Pull Request (PR)
 
@@ -470,7 +670,7 @@ Post completion comment to issue with:
 gh pr merge <N> --squash
 
 # 2. Clean up worktree (removes local worktree + branch)
-./scripts/dev/cleanup-worktree.sh feature/<issue-number>-*
+./scripts/cleanup-worktree.sh feature/<issue-number>-*
 
 # 3. Issue auto-closes if commit message contains "Fixes #N"
 ```
@@ -494,6 +694,16 @@ 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)
+
+After the PR is created (or earlier if the workflow exits gracefully), release the lock so other sessions can claim it:
+
+```bash
+npx sequant locks release <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.
+
 ## Iteration Tracking
 
 Track iterations to prevent infinite loops:
@@ -592,15 +802,24 @@ Ready for human review and merge.
 
 ## Error Recovery
 
+**Concurrency lock cleanup (#625, applies to every abort path below):**
+
+```bash
+npx sequant locks release <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.
+
 **If spec fails:**
 - Check issue exists and is readable
 - Verify GitHub CLI authentication
+- Release lock (see top of section)
 - Exit with clear error
 
 **If exec fails (build/test):**
 - Check error logs
 - Attempt targeted fix
-- If persistent, document and exit
+- If persistent: release lock, document, and exit
 
 **If test loop exhausted:**
 - Document remaining failures
@@ -693,10 +912,31 @@ sequant merge --check         # Verify no cross-issue conflicts
 
 ---
 
+## State Tracking
+
+**IMPORTANT:** `/fullsolve` is an orchestrator and manages state for child skills.
+
+### Orchestrator Responsibilities
+
+As an orchestrator, `/fullsolve` must:
+
+1. **Set orchestration context** for child skills:
+   ```bash
+   export SEQUANT_ORCHESTRATOR=fullsolve
+   export SEQUANT_PHASE=<current-phase>
+   export SEQUANT_ISSUE=<issue-number>
+   export SEQUANT_WORKTREE=<worktree-path>
+   ```
+
+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.
+
+---
+
 ## Output Verification
 
 **Before responding, verify your output includes ALL of these:**
 
+- [ ] **Risk Assessment (from QA)** - Likely failure mode and coverage gaps stated
 - [ ] **Progress Table** - Phase, iterations, and status for each phase
 - [ ] **AC Coverage** - Each AC marked MET/PARTIALLY_MET/NOT_MET
 - [ ] **Quality Metrics** - Tests passed, build status, type issues