sequant 2.1.2 → 2.3.0

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

@@ -0,0 +1,109 @@
+# Predicted file-collision detection
+
+`/assess` Step 5 inspects two sources of overlap between PROCEED issues:
+
+1. **Active-worktree overlap.** For each running worktree, `git diff --name-only main...HEAD` is intersected with the assessed issues' likely-touched files. Catches in-flight work.
+2. **Predicted file-collision (this document).** For each pair of unstarted PROCEED issues, the detector reads issue bodies and predicts which pairs will modify the same file once both run in parallel worktrees.
+
+This document is the tunable surface for the predicted-collision heuristic. The skill prose in `SKILL.md` names the detection functions; the patterns and the exclusion list live here so they can change without skill edits.
+
+## Trigger
+
+The detector runs automatically during Step 5 whenever ≥2 PROCEED issues are present in the assessment. Single-issue assessments skip it.
+
+## Path-extraction heuristics
+
+For each issue body, paths are extracted in this order:
+
+### 1. Strip code blocks and HTML comments
+
+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.
+
+### 2. Backtick-quoted source paths (PATH_REGEX)
+
+Backtick-quoted paths starting with one of the tracked roots and ending in a known source extension are extracted verbatim:
+
+```
+`(.claude|templates|skills|src|bin|docs)/<path-segment>+\.(md|ts|tsx|json|sh)`
+```
+
+Examples that match:
+
+- `` `.claude/skills/assess/SKILL.md` ``
+- `` `src/lib/foo.ts` ``
+- `` `templates/scripts/dev/foo.sh` ``
+
+Examples that **don't** match:
+
+- `` `phase-mapper.ts` `` — no directory prefix; too generic to disambiguate
+- `` `.claude/skills/**/*.md` `` — glob, not a literal path
+- `` `references/foo.md` `` — `references` is not a tracked root (it lives under `skills/<name>/`)
+
+### 3. Canonical bare form for skill files
+
+Skill files have three byte-identical mirrors at `.claude/skills/<name>/...`, `templates/skills/<name>/...`, `skills/<name>/...`. Treating the mirrors as separate paths would produce 3× the `Order:` lines and 6× the warnings for one logical conflict.
+
+The detector normalizes all three mirror prefixes to the bare subpath at extraction time:
+
+| Input (in issue body) | Canonical |
+|-----------------------|-----------|
+| `` `.claude/skills/qa/SKILL.md` `` | `qa/SKILL.md` |
+| `` `templates/skills/qa/SKILL.md` `` | `qa/SKILL.md` |
+| `` `skills/qa/SKILL.md` `` | `qa/SKILL.md` |
+| `` `qa/SKILL.md` `` (under 3-dir sync) | `qa/SKILL.md` |
+
+This is the form that appears in `Order:` lines and `⚠` warnings.
+
+### 4. Bare `<name>/SKILL.md` references (gated on 3-dir sync)
+
+When the body also signals "3-dir sync" (regex below), bare skill-file mentions like `` `qa/SKILL.md` `` and `` `spec/SKILL.md` `` are added to the path set in canonical form. The 3-dir-sync gate prevents over-extraction from incidental skill-file references in prose.
+
+3-dir-sync language is matched by:
+
+```
+/3[- ]dir(?:ectory)?\s+sync|across\s+all\s+three\s+skill\s+directories|across\s+(?:the\s+)?three\s+skill\s+directories/i
+```
+
+### 5. Slash-command-skill derivation (gated on 3-dir sync)
+
+When the body signals 3-dir sync, every `/<skill>` slash-command mention is also added as `<skill>/SKILL.md` (canonical bare form) — provided `<skill>` matches a known skill name. This catches issues that describe section changes via `/qa Section 6c`-style notation rather than naming the file path.
+
+The known-skill-name list lives in `KNOWN_SKILL_NAMES` in `src/lib/assess-collision-detect.ts`. Keep it in sync with the actual skill set under `skills/`. Adding a new skill? Append its name here.
+
+Slash-command derivation requires the same fenced-code-block / HTML-comment stripping — `/qa` mentioned only inside a code block does **not** trigger derivation.
+
+## False-positive guards
+
+### Globally excluded paths
+
+These paths are stripped from every issue's path set before pairwise intersection. They are paths that virtually every PROCEED issue tends to touch — including them would flag every batch as colliding and train users to ignore the warning.
+
+- `CHANGELOG.md` — every PROCEED issue updates the unreleased section
+- `package-lock.json` — alphabetically merged in practice; collisions are rare in practice
+- `yarn.lock`
+- `pnpm-lock.yaml`
+
+`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
+
+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.
+
+### Path-shape constraints
+
+The PATH_REGEX requires a directory prefix (one of the six tracked roots) and a known source extension. Bare filenames in prose (e.g. "phase-mapper.ts behavior") and glob patterns (`**/*.md`) are not extracted.
+
+## 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.
+- **Cost.** For 13 issues (the realistic batch ceiling), pairwise comparison is 78 pairs — cheap, no real performance concern. Don't optimize prematurely.
+
+## Output rules
+
+The detector returns `CollisionResult[]` from `detectFileCollisions`. The formatter (`formatCollisionAnnotations`) renders annotations in the dashboard 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.
+
+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/docs/SKILL.md

@@ -55,13 +55,63 @@ gh pr list --search "head:feature/<issue-number>" --json number,headRefName
 **Step 3:** Analyze the implementation diff:
 ```bash
 # If PR exists:
-gh pr diff <pr-number> 
+gh pr diff <pr-number>
 
 # If no PR, use git diff from feature branch:
 git diff main...HEAD --name-only
 git diff main...HEAD
 ```
 
+**Step 4:** Detect documentation-only changes:
+```bash
+# Count non-documentation files changed
+non_doc_files=$(git diff main...HEAD --name-only | grep -vE '\.(md|mdx)$|^docs/' | wc -l | xargs || true)
+```
+
+**Decision Logic:**
+```
+IF non_doc_files == 0 THEN
+  # Documentation-only issue detected
+  # Skip template generation, post confirmation comment instead
+  # See Section 2a: Documentation-Only Early Exit
+ELSE
+  # Continue with normal documentation generation
+END IF
+```
+
+### 2a. Documentation-Only Early Exit
+
+When only documentation files (`.md`, `.mdx`, or files in `docs/`) were modified, skip template generation and post a confirmation comment instead.
+
+**Detection criteria - ALL of these must be true:**
+- `git diff main...HEAD --name-only` returns files
+- All changed files match: `*.md`, `*.mdx`, or `docs/*`
+
+**Early exit action:**
+
+1. **Post confirmation comment to GitHub issue:**
+   ```bash
+   gh issue comment <issue-number> --body "$(cat <<'EOF'
+   ## Documentation Review Complete
+
+   This issue contains **documentation-only changes**. No additional documentation generation required.
+
+   ### Files Modified:
+   [List of changed .md/.mdx/docs/ files]
+
+   ### Status:
+   ✅ Documentation changes are ready for review and merge.
+
+   ---
+   Ready to merge!
+   EOF
+   )"
+   ```
+
+2. **Exit without generating template documentation.**
+
+**Skip to end of workflow** - do not proceed to Section 2 (Auto-Detect Documentation Type) or beyond.
+
 ### 2. Auto-Detect Documentation Type
 
 Determine documentation type based on changed files:
@@ -72,25 +122,45 @@ Determine documentation type based on changed files:
 - Files in `lib/admin/`
 - Admin-related API routes
 
-**User-Facing Documentation** (`docs/features/`):
-- Files in `app/[city]/`
-- Files in `components/` (non-admin)
-- Public-facing pages or features
+**Developer Tool Documentation** (`docs/features/`):
+- Files in `src/commands/`, `bin/`, `src/mcp/`
+- CLI commands, MCP tools, scripts
+- Configuration options, SDK integrations
+
+**Infra / Scaffold Documentation** (`docs/features/`):
+- Root config files (`package.json`, `*.config.{ts,js,mjs,cts,cjs,mts}`)
+- TypeScript / JavaScript project config (`tsconfig.json`, `jsconfig.json`)
+- Environment templates (`.env.example`)
+- Next.js layout/page files (`src/app/**/layout.tsx`, `src/app/**/page.tsx`)
+- Middleware (`src/middleware.ts`)
+- Framework config (`payload.config.*`, `drizzle.config.*`, `next.config.*`, `vite.config.*`, `vitest.config.*`)
+
+Everything else (user-facing pages, non-admin components, public-facing features) falls through to the default `developer-tool` template.
 
 **Decision Logic:**
 ```
 IF any file path contains "/admin/" THEN
   type = "admin"
   output_dir = "docs/admin/"
+  template = "admin" (Section 3a)
+ELSE IF any file path matches "src/commands/|bin/|src/mcp/|scripts/" THEN
+  type = "developer-tool"
+  output_dir = "docs/features/"
+  template = "developer-tool" (Section 3b)
+ELSE IF any file path matches "package\.json$|.*\.config\.(ts|js|mjs|cts|cjs|mts)$|(ts|js)config\.json$|\.env\.example$|^src/app/.*(layout|page)\.tsx$|^src/middleware\.ts$|^(payload|drizzle|next|vite|vitest)\.config\." THEN
+  type = "developer-tool"
+  output_dir = "docs/features/"
+  template = "developer-tool" (Section 3b)
 ELSE
-  type = "feature"
+  type = "developer-tool"
   output_dir = "docs/features/"
+  template = "developer-tool" (Section 3b)
 END IF
 ```
 
-### 3. Documentation Template
+### 3a. Admin/UI Documentation Template
 
-Generate documentation using this template:
+Use this template for admin pages and UI features:
 
 ```markdown
 # [Feature Name]
@@ -130,11 +200,6 @@ Generate documentation using this template:
 2. [Step 2]
 3. [Step 3]
 
-### [Workflow 2: e.g., "Bulk Edit Multiple Items"]
-
-1. [Step 1]
-2. [Step 2]
-
 ## Troubleshooting
 
 ### [Common Issue 1]
@@ -143,20 +208,69 @@ Generate documentation using this template:
 
 **Solution:** [How to fix it]
 
-### [Common Issue 2]
+---
 
-**Symptoms:** [What the user sees]
+*Generated for Issue #[number] on [date]*
+```
 
-**Solution:** [How to fix it]
+### 3b. Developer Tool Documentation Template
+
+Use this template for CLI commands, MCP tools, scripts, and developer-facing features. Structure around the user's journey, not the API surface.
+
+```markdown
+# [Feature Name]
+
+[1-2 sentence summary: what it does and why you'd use it.]
+
+## Prerequisites
+
+[Everything needed before this works. Be exhaustive — list tools, auth, config. Include verification commands.]
+
+1. **[Requirement 1]** — `verification command`
+2. **[Requirement 2]** — `verification command`
+
+## Setup
+
+[Step-by-step to go from zero to working. If setup differs per environment/client/platform, show each separately with clear labels.]
+
+## What You Can Do
+
+[Real examples of usage in natural language or command form. Show the most common actions first.]
+
+## What to Expect
+
+[Set expectations: how long things take, what output looks like, where results go. Address "it looks like nothing is happening" if applicable.]
+
+## [Command/Tool] Reference
+
+[Parameter tables, flags, options. Put this AFTER the narrative sections — users need context before reference.]
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+
+## Troubleshooting
+
+[Real failure scenarios users will hit. Lead with what they see, then the fix.]
+
+### [Problem user sees]
+
+[Cause and solution]
 
 ---
 
 *Generated for Issue #[number] on [date]*
 ```
 
+**Key differences from admin template:**
+- No "Access / URL / Menu / Permissions" section (not applicable to CLI tools)
+- Prerequisites section is mandatory (CLI tools have more dependencies)
+- "What to Expect" section addresses timing, output location, async behavior
+- Setup may vary per environment — show each variant
+- Reference tables come after narrative, not before
+
 ### 4. Content Guidelines
 
-**Focus on operational usage, not technical implementation:**
+**For admin/UI features — focus on operational usage:**
 
 - "Click the 'Approve' button to publish the item"
 - NOT: "The `approveItem` function updates the database"
@@ -164,16 +278,19 @@ Generate documentation using this template:
 - "Wait for the green success message"
 - NOT: "The API returns a 200 status code"
 
+**For developer tools — focus on the user's journey:**
+
+- "Run `sequant serve` to start the MCP server"
+- NOT: "The `serveCommand` function creates an MCP server instance"
+
+- "This takes 10–20 minutes. Your editor will appear idle — that's normal."
+- NOT: "The tool uses `spawnSync` with a 30-minute timeout"
+
 **Be specific and actionable:**
 
 - "Navigate to Admin → Items → Review Queue"
 - NOT: "Go to the review page"
 
-**Include visual cues when relevant:**
-
-- "Look for the blue 'Edit' icon next to each row"
-- NOT: "Click the edit button"
-
 **Document common workflows end-to-end:**
 
 - "To approve an item: 1. Open Review Queue, 2. Click item name, 3. Review details, 4. Click Approve"
@@ -239,6 +356,8 @@ Before completing, verify:
 - [ ] Correct folder (`docs/admin/` vs `docs/features/`)
 - [ ] Summary comment posted to issue
 
+**Note:** For documentation-only issues (detected in Step 4), skip this checklist and use the simplified confirmation comment from Section 2a instead.
+
 ## Workflow Integration
 
 The `/docs` command is the final step before merging:

package/templates/skills/exec/SKILL.md

@@ -27,8 +27,8 @@ allowed-tools:
   - Bash(git push:*)
   - Bash(git worktree:*)
   # Worktree management
-  - Bash(./scripts/dev/new-feature.sh:*)
-  - Bash(./scripts/dev/cleanup-worktree.sh:*)
+  - Bash(./scripts/new-feature.sh:*)
+  - Bash(./scripts/cleanup-worktree.sh:*)
   # GitHub CLI
   - Bash(gh issue view:*)
   - Bash(gh issue comment:*)
@@ -273,7 +273,7 @@ When worktree creation is needed (standalone mode, no existing worktree):
 1. **Start worktree creation as background task:**
    ```bash
    # From main repo, start worktree creation in background
-   ./scripts/dev/new-feature.sh <issue-number> &
+   ./scripts/new-feature.sh <issue-number> &
    WORKTREE_PID=$!
    echo "Worktree creation started (PID: $WORKTREE_PID)"
    ```
@@ -461,8 +461,8 @@ echo "Current branch: $CURRENT_BRANCH"
 
 **If on main/master branch:**
 1. **STOP** - Do not implement directly on main
-2. Create a feature worktree first: `./scripts/dev/new-feature.sh <issue-number>`
-   - For custom base branch: `./scripts/dev/new-feature.sh <issue-number> --base <branch>`
+2. Create a feature worktree first: `./scripts/new-feature.sh <issue-number>`
+   - For custom base branch: `./scripts/new-feature.sh <issue-number> --base <branch>`
 3. Navigate to the worktree before making any changes
 
 **Why this matters:** Work done directly on main can be lost during sync operations (git reset, git pull --rebase, etc.). Worktrees provide isolation and safe recovery through branches.
@@ -484,9 +484,9 @@ echo "Current branch: $CURRENT_BRANCH"
    ```bash
    # Step 1: Start worktree creation in background
    # For default (main) base:
-   ./scripts/dev/new-feature.sh <issue-number> &
+   ./scripts/new-feature.sh <issue-number> &
    # For custom base branch (e.g., feature integration branch):
-   ./scripts/dev/new-feature.sh <issue-number> --base feature/dashboard &
+   ./scripts/new-feature.sh <issue-number> --base feature/dashboard &
    WORKTREE_PID=$!
 
    # Step 2: Gather context while worktree creates (see Section 2)
@@ -517,7 +517,7 @@ echo "Current branch: $CURRENT_BRANCH"
 4. **After implementation is complete:**
    - Push the branch: `git push -u origin feature/<branch-name>`
    - Create PR (manually or via script)
-   - The worktree will be cleaned up after PR merge using `./scripts/dev/cleanup-worktree.sh <branch-name>`
+   - The worktree will be cleaned up after PR merge using `./scripts/cleanup-worktree.sh <branch-name>`
 
 **Important:** Always work in the worktree directory, not the main repository, once the worktree is created.
 
@@ -806,16 +806,6 @@ After implementation is complete and all checks pass, create and verify the PR:
    - If PR exists: Record the URL from `gh pr view` output
    - If PR creation failed: Record the error and include manual creation instructions
 
-6. **Record PR info in workflow state:**
-   ```bash
-   # Extract PR number and URL from gh pr view output, then update state
-   PR_INFO=$(gh pr view --json number,url)
-   PR_NUMBER=$(echo "$PR_INFO" | jq -r '.number')
-   PR_URL=$(echo "$PR_INFO" | jq -r '.url')
-   npx tsx scripts/state/update.ts pr <issue-number> "$PR_NUMBER" "$PR_URL"
-   ```
-   This enables `--cleanup` to detect merged PRs and auto-remove state entries.
-
 **PR Verification Failure Handling:**
 
 If `gh pr view` fails after retry:
@@ -1546,6 +1536,8 @@ Look in the issue comments (especially from `/spec`) for:
 
 2. **Determine model for each task:**
 
+   <!-- Note: model param inert per anthropics/claude-code#43869; the parsing
+        logic below reactivates automatically when the upstream fix ships. -->
    Check for model annotations in the task line: `[model: haiku]` or `[model: sonnet]`
 
    **Model Selection Priority:**
@@ -1924,37 +1916,6 @@ You may be invoked multiple times for the same issue. Each time, re-establish co
 
 ---
 
-## State Tracking
-
-**IMPORTANT:** Update workflow state when running standalone (not orchestrated).
-
-### Check Orchestration Mode
-
-The orchestration check happens automatically when you run the state update script - it exits silently if `SEQUANT_ORCHESTRATOR` is set.
-
-### State Updates (Standalone Only)
-
-When NOT orchestrated (`SEQUANT_ORCHESTRATOR` is not set):
-
-**At skill start:**
-```bash
-npx tsx scripts/state/update.ts start <issue-number> exec
-```
-
-**On successful completion:**
-```bash
-npx tsx scripts/state/update.ts complete <issue-number> exec
-```
-
-**On failure:**
-```bash
-npx tsx scripts/state/update.ts fail <issue-number> exec "Error description"
-```
-
-**Why this matters:** State tracking enables dashboard visibility, resume capability, and workflow orchestration. Skills update state when standalone; orchestrators handle state when running workflows.
-
----
-
 ## Output Verification
 
 **Before responding, verify your output includes ALL of these:**

package/templates/skills/fullsolve/SKILL.md

@@ -34,6 +34,9 @@ allowed-tools:
   - 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
@@ -244,6 +247,29 @@ Before creating any files, check if they already exist:
 
 **If work already exists:** Skip to the appropriate phase (e.g., if implementation is done, go to Phase 3 or 4).
 
+### 0.3 Acquire Concurrency Lock (#625)
+
+**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
+# 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
+```
+
+**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>`.
+
+**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.
+
 ## Phase 1: Planning (SPEC)
 
 **Invoke the `/spec` skill** to plan implementation and extract acceptance criteria.
@@ -284,8 +310,14 @@ After `/spec` completes, extract and store:
 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
+# Release before halting — see Phase 0.3 release contract.
+npx sequant locks release <issue-number> || true
+```
+
 ```markdown
 ## Spec Failed
 
@@ -355,6 +387,11 @@ while exec_iteration < MAX_EXEC_ITERATIONS:
 ```
 
 **If all iterations exhausted:**
+```bash
+# Release before halting — see Phase 0.3 release contract.
+npx sequant locks release <issue-number> || true
+```
+
 ```markdown
 ## Exec Failed
 
@@ -446,7 +483,7 @@ while test_iteration < MAX_TEST_ITERATIONS:
         break
 
     # Use /loop to fix failures
-    Skill(skill: "loop", args: "<issue-number> --phase test")
+    Skill(skill: "sequant:loop", args: "<issue-number> --phase test")
     test_iteration += 1
 ```
 
@@ -504,11 +541,29 @@ When `/qa` detects `SEQUANT_ORCHESTRATOR`, it:
 
 ### 4.3 QA Loop (Max 2 iterations)
 
-If verdict is not `READY_FOR_MERGE`, invoke `/loop` to fix and re-run QA:
+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 < 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":
@@ -524,7 +579,7 @@ while qa_iteration < MAX_QA_ITERATIONS:
         break
 
     # Use /loop to fix issues (AC_NOT_MET)
-    Skill(skill: "loop", args: "<issue-number> --phase qa")
+    Skill(skill: "sequant:loop", args: "<issue-number> --phase qa")
     qa_iteration += 1
 ```
 
@@ -615,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"
 ```
@@ -639,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:
@@ -737,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
@@ -854,33 +928,7 @@ As an orchestrator, `/fullsolve` must:
    export SEQUANT_WORKTREE=<worktree-path>
    ```
 
-2. **Initialize issue state at workflow start:**
-   ```bash
-   npx tsx scripts/state/update.ts init <issue-number> "<issue-title>"
-   ```
-
-3. **Update phase status** at each transition:
-   ```bash
-   # Before invoking child skill
-   npx tsx scripts/state/update.ts start <issue-number> <phase>
-
-   # After child skill completes
-   npx tsx scripts/state/update.ts complete <issue-number> <phase>
-
-   # If child skill fails
-   npx tsx scripts/state/update.ts fail <issue-number> <phase> "Error"
-   ```
-
-4. **Update final status** after workflow completes:
-   ```bash
-   # On READY_FOR_MERGE
-   npx tsx scripts/state/update.ts status <issue-number> ready_for_merge
-
-   # On failure
-   npx tsx scripts/state/update.ts status <issue-number> blocked
-   ```
-
-**Why child skills skip state updates:** When `SEQUANT_ORCHESTRATOR` is set, child skills defer state management to the orchestrator to avoid duplicate updates.
+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.
 
 ---