sequant 2.2.0 → 2.3.0

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.
 
@@ -1536,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:**

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

package/templates/skills/loop/SKILL.md

@@ -169,6 +169,34 @@ mcp__context7__query-docs({
 - Maintain type safety (no `any`)
 - Don't delete or modify unrelated tests
 
+### Step 5.5: No-Diff Guard (issue #581)
+
+Before yielding back to `/qa`, verify Step 5 actually produced a diff. If neither HEAD nor the working tree (excluding `.sequant/` state writes) changed, the fix attempt was a silent no-op — re-running `/qa` would produce the same verdict at the same SHA. Halt with `LOOP_NO_DIFF` so the orchestrator escalates to manual intervention rather than wasting another QA cycle.
+
+**Take a baseline snapshot at the START of Step 5:**
+
+```bash
+BEFORE_SNAPSHOT=$(npx tsx scripts/qa-stagnation.ts snapshot)
+# JSON: {"sha": "<HEAD>", "dirty": ["<path>", ...]} — .sequant/ paths excluded
+```
+
+**Compare AFTER Step 5 completes (before Step 6 re-validates):**
+
+```bash
+AFTER_SNAPSHOT=$(npx tsx scripts/qa-stagnation.ts snapshot)
+DECISION=$(npx tsx scripts/qa-stagnation.ts compare-snapshot "$BEFORE_SNAPSHOT" "$AFTER_SNAPSHOT")
+# JSON: {"progressed": true|false, "reason"?: "LOOP_NO_DIFF", "message": "..."}
+
+if [[ $(echo "$DECISION" | jq -r '.progressed') == "false" ]]; then
+  # Record stagnation telemetry; halt — manual intervention required.
+  npx tsx scripts/qa-stagnation.ts record <issue-number> <iteration> LOOP_NO_DIFF --verdict=NO_LOOP_PROGRESS || true
+  echo "ERROR: /loop made no commit and no working-tree changes (excluding .sequant/) — manual intervention required."
+  exit 1
+fi
+```
+
+State-file writes (anything under `.sequant/`) are deliberately excluded from the dirty comparison — `recordStagnation` writes there itself, and per issue #581's open question those writes are not progress.
+
 ### Step 6: Re-run Validation
 
 After fixes are applied, re-run the phase that found issues: