sequant 1.20.3 → 2.0.1

package/templates/skills/exec/SKILL.md

@@ -588,6 +588,51 @@ echo "Current branch: $CURRENT_BRANCH"
 - Documents intentional deferrals
 - Enables better QA in `/qa` phase
 
+### 3e2. Simulate QA Before PR (REQUIRED)
+
+**Purpose:** Prevent first-pass QA failures by simulating the QA reviewer's perspective before creating a PR. Root cause analysis of multi-attempt QA issues (#448) found that the majority of first-pass failures stem from gaps exec could have caught with deliberate self-verification.
+
+**Top failure patterns exec must check for (from analysis of 6 multi-attempt issues):**
+
+| Pattern | Frequency | What to check |
+|---------|-----------|---------------|
+| Test coverage gaps | 50% (3/6 issues) | Changed files have corresponding tests |
+| Incomplete self-verification | 17% (1/6 issues) | Each AC verified against literal wording, not just spirit |
+| Lint/build not run pre-PR | 17% (1/6 issues) | `npm run lint` + `npm run build` pass locally |
+
+*Note: Remaining 33% were QA detection issues, addressed separately in QA skill.*
+
+**Simulate QA Checklist (answer each before creating PR):**
+
+1. **Test-to-Change Alignment:** For each source file you modified:
+   ```bash
+   # List changed source files (excluding tests)
+   changed=$(git diff main...HEAD --name-only | grep -E '\.(ts|tsx|js|jsx)$' | grep -v -E '\.(test|spec)\.' || true)
+
+   # For each, verify a corresponding test exists and covers the change
+   for file in $changed; do
+     base=$(basename "$file" | sed 's/\.[^.]*$//')
+     test_exists=$(find . -name "${base}.test.*" -o -name "${base}.spec.*" 2>/dev/null | head -1 || true)
+     if [[ -z "$test_exists" ]]; then
+       echo "WARNING NO TEST: $file"
+     fi
+   done
+   ```
+   - If critical files lack tests, add tests before PR creation
+   - If tests exist but don't cover the specific change, note as known gap
+
+2. **QA Reviewer Perspective:** Ask yourself:
+   - "If I were reviewing this PR for the first time, what would I flag?"
+   - "Are there any 'I'll fix it later' shortcuts that QA will catch?"
+   - "Did I actually run the feature, or just verify it compiles?"
+
+**If any check reveals a gap:**
+- Fix the gap before creating the PR
+- Re-run build/lint/tests after fixing
+- Update the AC verification table
+
+**Do NOT skip this step.** This single checkpoint addresses the most common first-pass QA failure patterns.
+
 ### 3f. CHANGELOG Update (REQUIRED for user-facing changes)
 
 **Purpose:** Ensure all user-facing changes are documented in the CHANGELOG before PR creation. This prevents documentation gaps and reduces release overhead.
@@ -1161,7 +1206,7 @@ for script in $shell_scripts; do
   # 3. Unused function detection
   funcs=$(grep -oE "^[a-zA-Z_]+\(\)" "$script" | sed 's/()//' || true)
   for func in $funcs; do
-    calls=$(grep -c "\b${func}\b" "$script" || echo "0")
+    calls=$(grep -c "\b${func}\b" "$script" || true)
     if [[ $calls -lt 2 ]]; then
       echo "⚠️ Function '$func' defined but possibly not called"
     fi
@@ -1636,6 +1681,22 @@ When retrying a failed agent, use the error recovery template from [prompt-templ
 
 Before each commit, self-check against these standards:
 
+### 0. Branch Verification
+
+**CRITICAL:** Verify you are on the correct feature branch, not main/master.
+
+```bash
+CURRENT_BRANCH=$(git branch --show-current)
+if [[ "$CURRENT_BRANCH" == "main" || "$CURRENT_BRANCH" == "master" ]]; then
+  echo "❌ ERROR: On $CURRENT_BRANCH — do NOT commit here."
+  echo "   Navigate to the feature worktree or create a branch first."
+  exit 1
+fi
+echo "✓ On branch: $CURRENT_BRANCH"
+```
+
+**Why:** Sub-agents and shell context resets can silently switch the working directory back to main. Without this check, commits land on main instead of the feature branch.
+
 ### 1. Scope Check
 Does this change directly address an AC item?
 - **Yes** → Proceed
@@ -1724,6 +1785,8 @@ The goal is to satisfy AC with the smallest, safest change possible.
 2. "If this feature broke tomorrow, would the current tests catch it?"
 3. "What's the weakest part of this implementation?"
 4. "Am I reporting success metrics without honest self-evaluation?"
+5. "For each changed source file, does a corresponding test file exist? If not, why is that acceptable?"
+6. "Did I run `npm run lint` and fix all errors, or am I hoping CI will pass?"
 
 **Include this section in your output:**
 

package/templates/skills/fullsolve/SKILL.md

@@ -143,7 +143,14 @@ When posting progress comments after each phase, append the appropriate marker:
 ### 0.1 Git State Verification
 
 ```bash
-# Check current branch and recent commits
+# Check current branch — warn if on main/master
+CURRENT_BRANCH=$(git branch --show-current)
+echo "Current branch: $CURRENT_BRANCH"
+if [[ "$CURRENT_BRANCH" == "main" || "$CURRENT_BRANCH" == "master" ]]; then
+  echo "⚠️  WARNING: On $CURRENT_BRANCH — will need feature branch before committing"
+fi
+
+# Check recent commits
 git log --oneline -5 --stat
 
 # Check for any existing work on this issue
@@ -412,6 +419,30 @@ while qa_iteration < 2:
 
 ## Phase 5: Pull Request (PR)
 
+### 5.0 Branch Verification Gate
+
+**CRITICAL: Verify you are on the correct feature branch before committing or creating a PR.**
+
+```bash
+CURRENT_BRANCH=$(git branch --show-current)
+echo "Current branch: $CURRENT_BRANCH"
+
+# HARD GATE: Must be on a feature branch, not main/master
+if [[ "$CURRENT_BRANCH" == "main" || "$CURRENT_BRANCH" == "master" ]]; then
+  echo "❌ ERROR: On $CURRENT_BRANCH — commits must NOT land on main."
+  echo "   Fix: git checkout feature/<issue-number>-* or create a new branch."
+  exit 1
+fi
+
+# Soft check: branch should match the issue number
+if ! echo "$CURRENT_BRANCH" | grep -q "<issue-number>"; then
+  echo "⚠️  WARNING: Branch '$CURRENT_BRANCH' does not contain issue number <issue-number>."
+  echo "   Verify this is the correct branch before continuing."
+fi
+```
+
+**Why this matters:** Sub-agents and shell context resets can silently switch the working directory back to main. Without this check, commits land on main instead of the feature branch, requiring messy recovery (cherry-picks, force pushes, re-created PRs).
+
 ### 5.1 Create PR (if not exists)
 
 ```bash
@@ -435,8 +466,8 @@ Post completion comment to issue with:
 **IMPORTANT:** Merge the PR first, then clean up the worktree.
 
 ```bash
-# 1. Merge PR (--delete-branch deletes remote; local deletion will fail but that's OK)
-gh pr merge <N> --squash --delete-branch
+# 1. Merge PR (without --delete-branch; cleanup happens after success)
+gh pr merge <N> --squash
 
 # 2. Clean up worktree (removes local worktree + branch)
 ./scripts/dev/cleanup-worktree.sh feature/<issue-number>-*
@@ -444,7 +475,7 @@ gh pr merge <N> --squash --delete-branch
 # 3. Issue auto-closes if commit message contains "Fixes #N"
 ```
 
-**Why this order matters:** The cleanup script checks if the PR is merged before proceeding. The `--delete-branch` flag will fail to delete the local branch (worktree conflict) but successfully deletes the remote branch. The cleanup script then handles the local branch removal.
+**Why this order matters:** The cleanup script checks if the PR is merged before proceeding. Merging without `--delete-branch` avoids worktree lock conflicts. The post-tool hook and cleanup script handle branch removal after merge succeeds. If the merge fails, the worktree is preserved so work isn't lost.
 
 ### 5.4 Post-Merge Verification