sequant 1.11.0 → 1.12.0

package/templates/skills/qa/SKILL.md

@@ -16,6 +16,9 @@ allowed-tools:
   - Bash(gh pr view:*)
   - Bash(gh pr diff:*)
   - Bash(gh pr comment:*)
+  - Bash(semgrep:*)
+  - Bash(npx semgrep:*)
+  - Bash(npx tsx scripts/semgrep-scan.ts:*)
   - Task
   - AgentOutputTool
 ---
@@ -120,11 +123,11 @@ If no feature worktree exists (work was done directly on main):
 
 **Spawn ALL THREE agents in a SINGLE message:**
 
-1. `Task(subagent_type="quality-checker", model="haiku", prompt="Run type safety and deleted tests checks on the current branch vs main. Report: type issues count, deleted tests, verdict.")`
+1. `Task(subagent_type="general-purpose", model="haiku", prompt="Run type safety and deleted tests checks on the current branch vs main. Report: type issues count, deleted tests, verdict.")`
 
-2. `Task(subagent_type="quality-checker", model="haiku", prompt="Run scope and size checks on the current branch vs main. Report: files count, diff size, size assessment.")`
+2. `Task(subagent_type="general-purpose", model="haiku", prompt="Run scope and size checks on the current branch vs main. Report: files count, diff size, size assessment.")`
 
-3. `Task(subagent_type="quality-checker", model="haiku", prompt="Run security scan on changed files in current branch vs main. Report: critical/warning/info counts, verdict.")`
+3. `Task(subagent_type="general-purpose", model="haiku", prompt="Run security scan on changed files in current branch vs main. Report: critical/warning/info counts, verdict.")`
 
 **Add RLS check if admin files modified:**
 ```bash
@@ -133,10 +136,52 @@ admin_modified=$(git diff main...HEAD --name-only | grep -E "^app/admin/" | head
 
 See [quality-gates.md](references/quality-gates.md) for detailed verdict synthesis.
 
-### Using MCP Tools (Optional)
+### MCP Tools (Optional - Graceful Degradation)
 
-- **Sequential Thinking:** For complex multi-step analysis
-- **Context7:** For broader pattern context and library documentation
+MCP tools enhance `/qa` but are **not required**. The skill works fully without them.
+
+#### MCP Availability Check
+
+Before using MCP tools, verify they are available. If unavailable, use the fallback strategies.
+
+| MCP Tool | Purpose | Fallback When Unavailable |
+|----------|---------|---------------------------|
+| Sequential Thinking | Complex multi-step analysis | Use explicit step-by-step reasoning in response |
+| Context7 | Library documentation lookup | Use WebSearch or codebase pattern search |
+
+#### Sequential Thinking Fallback
+
+**When to use Sequential Thinking:**
+- Complex architectural trade-offs during code review
+- Multi-dimensional quality assessment
+- Analyzing interconnected issues across files
+
+**If unavailable:**
+1. Structure your analysis with explicit numbered steps
+2. Document each concern systematically before synthesizing verdict
+3. Use a pros/cons format for trade-off decisions
+
+```markdown
+## Analysis Steps (Manual Sequential Thinking)
+
+**Step 1:** [Analyze first dimension - correctness]
+**Step 2:** [Analyze second dimension - maintainability]
+**Step 3:** [Analyze third dimension - performance]
+**Step 4:** [Synthesize findings into verdict]
+```
+
+#### Context7 Fallback
+
+**When to use Context7:**
+- Verifying implementation matches library best practices
+- Checking if API usage follows recommended patterns
+- Understanding framework-specific conventions in reviewed code
+
+**If unavailable:**
+1. Search codebase with Grep for existing usage patterns
+2. Use WebSearch for official library documentation
+3. Check similar implementations in the codebase as reference
+4. Review library's README or documentation in node_modules
 
 ### 1. Context and AC Alignment
 
@@ -180,9 +225,32 @@ See [testing-requirements.md](references/testing-requirements.md) for edge case
 
 Provide an overall verdict:
 
-- `READY_FOR_MERGE` — AC met and code quality is high ("A+")
-- `AC_MET_BUT_NOT_A_PLUS` — AC met, but meaningful improvements recommended
-- `AC_NOT_MET` — AC not fully met; additional implementation needed
+- `READY_FOR_MERGE` — ALL ACs are `MET` and code quality is high ("A+")
+- `AC_MET_BUT_NOT_A_PLUS` — ALL ACs are `MET`, but meaningful improvements recommended
+- `NEEDS_VERIFICATION` — ALL ACs are `MET` or `PENDING`, at least one requires external verification
+- `AC_NOT_MET` — One or more ACs are `NOT_MET` or `PARTIALLY_MET`
+
+**Verdict Determination Algorithm (REQUIRED):**
+
+```text
+1. Count AC statuses:
+   - met_count = ACs with status MET
+   - partial_count = ACs with status PARTIALLY_MET
+   - pending_count = ACs with status PENDING
+   - not_met_count = ACs with status NOT_MET
+
+2. Determine verdict (in order):
+   - IF not_met_count > 0 OR partial_count > 0:
+       → AC_NOT_MET (block merge)
+   - ELSE IF pending_count > 0:
+       → NEEDS_VERIFICATION (wait for verification)
+   - ELSE IF improvement_suggestions.length > 0:
+       → AC_MET_BUT_NOT_A_PLUS (can merge with notes)
+   - ELSE:
+       → READY_FOR_MERGE (A+ implementation)
+```
+
+**CRITICAL:** `PARTIALLY_MET` is NOT sufficient for merge. It MUST be treated as `NOT_MET` for verdict purposes.
 
 See [quality-gates.md](references/quality-gates.md) for detailed verdict criteria.
 
@@ -221,9 +289,11 @@ Produce a Markdown snippet for the PR/issue:
 ### 7. Update GitHub Issue
 
 Post the draft comment to GitHub and update labels:
+
 - `AC_NOT_MET`: add `needs-work` label
 - `READY_FOR_MERGE`: add `ready-for-review` label
 - `AC_MET_BUT_NOT_A_PLUS`: add `needs-improvement` label
+- `NEEDS_VERIFICATION`: add `needs-verification` label
 
 ### 8. Documentation Reminder
 

package/templates/skills/qa/references/quality-gates.md

@@ -9,14 +9,56 @@ Combine agent outputs into a unified quality assessment:
 | Type Safety Checker | Type issues count, verdict | High - blocking if issues > 3 |
 | Scope/Size Checker | Files changed, LOC, assessment | Medium - warning if very large |
 | Security Scanner | Critical/warning/info counts | High - blocking if criticals > 0 |
+| Semgrep Static Analysis | Critical/warning findings | High - blocking if criticals > 0 |
 | RLS Checker (conditional) | Violations found | High - blocking if violations |
 
 **Synthesis Rules:**
 - **Any FAIL verdict** → Flag as blocker in manual review
-- **Security criticals** → Block merge, require fix before proceeding
+- **Security criticals (including Semgrep)** → Block merge, require fix before proceeding
 - **All PASS** → Proceed with confidence to manual review
 - **WARN verdicts** → Note in review, verify manually
 
+## Semgrep Integration
+
+Semgrep provides static analysis for security vulnerabilities and anti-patterns.
+
+### Verdict Mapping
+
+| Semgrep Result | QA Verdict Impact |
+|----------------|-------------------|
+| Critical findings > 0 | **BLOCKING** - `AC_NOT_MET` |
+| Warning findings only | Non-blocking - note in review |
+| No findings | Pass - no impact |
+| Semgrep not installed | Skipped - graceful degradation |
+| Semgrep error | Non-blocking - log error |
+
+### Output Format
+
+```markdown
+## Static Analysis (Semgrep)
+
+✅ No critical findings
+⚠️ 2 warnings:
+  - src/api/users.ts:47 - Potential SQL injection (user input in query)
+  - src/utils/exec.ts:12 - Command injection risk (unsanitized shell arg)
+```
+
+### Stack-Aware Rulesets
+
+Semgrep uses stack-specific rulesets for targeted analysis:
+
+| Stack | Rulesets |
+|-------|----------|
+| Next.js | p/typescript, p/javascript, p/react, p/security-audit, p/secrets |
+| Python | p/python, p/django, p/flask, p/security-audit, p/secrets |
+| Go | p/golang, p/security-audit, p/secrets |
+| Rust | p/rust, p/security-audit, p/secrets |
+| Generic | p/security-audit, p/secrets |
+
+### Custom Rules
+
+Projects can add custom rules in `.sequant/semgrep-rules.yaml`. These are loaded alongside stack rules automatically.
+
 ## Verdict Criteria
 
 ### `READY_FOR_MERGE`
@@ -43,6 +85,17 @@ AC met, but one or more issues:
 
 **Action:** List specific improvements, but don't block merge if working
 
+### `NEEDS_VERIFICATION`
+
+All AC items are `MET`, but one or more items have `PENDING` status requiring external verification:
+
+- ⏳ CI/CD verification pending
+- ⏳ Manual testing not yet performed
+- ⏳ External dependency verification needed
+- ⏳ Production environment validation required
+
+**Action:** Complete pending verification, then re-run `/qa`
+
 ### `AC_NOT_MET`
 
 Any of:
@@ -55,6 +108,37 @@ Any of:
 
 **Action:** Block merge, list required fixes
 
+## Verdict Determination Algorithm
+
+**CRITICAL:** Follow this algorithm exactly when determining the verdict. Do NOT give `READY_FOR_MERGE` unless ALL conditions are met.
+
+```text
+1. Count AC statuses:
+   - met_count = ACs with status MET
+   - partial_count = ACs with status PARTIALLY_MET
+   - pending_count = ACs with status PENDING
+   - not_met_count = ACs with status NOT_MET
+
+2. Determine verdict (in order):
+   - IF not_met_count > 0 OR partial_count > 0:
+       → AC_NOT_MET (block merge)
+   - ELSE IF pending_count > 0:
+       → NEEDS_VERIFICATION (wait for verification)
+   - ELSE IF improvement_suggestions.length > 0:
+       → AC_MET_BUT_NOT_A_PLUS (can merge with notes)
+   - ELSE:
+       → READY_FOR_MERGE (A+ implementation)
+```
+
+| Verdict                  | When to Use                                              |
+|--------------------------|----------------------------------------------------------|
+| `READY_FOR_MERGE`        | ALL ACs are `MET`, no improvements needed                |
+| `AC_MET_BUT_NOT_A_PLUS`  | ALL ACs are `MET`, but minor improvements suggested      |
+| `NEEDS_VERIFICATION`     | ALL ACs are `MET` or `PENDING`, at least one is `PENDING`|
+| `AC_NOT_MET`             | ANY AC is `NOT_MET` or `PARTIALLY_MET`                   |
+
+**Important:** `PARTIALLY_MET` is NOT sufficient for merge. It must be treated as `NOT_MET` for verdict purposes.
+
 ## Code Review Decision Framework
 
 ### 1. Purpose Test

package/templates/skills/qa/references/semgrep-rules.md

@@ -0,0 +1,207 @@
+# Semgrep Integration Guide
+
+This guide explains how to configure and use Semgrep static analysis in the `/qa` workflow.
+
+## Overview
+
+Semgrep is a fast, open-source static analysis tool that finds bugs and enforces code standards. The `/qa` skill integrates Semgrep to automatically scan code changes for security vulnerabilities and anti-patterns.
+
+## Installation
+
+Semgrep is **optional**. If not installed, the `/qa` skill will gracefully skip Semgrep analysis.
+
+### Install Semgrep
+
+```bash
+# Using pip (recommended)
+pip install semgrep
+
+# Using Homebrew (macOS)
+brew install semgrep
+
+# Using npm (via npx - no install required)
+npx semgrep --version
+```
+
+### Verify Installation
+
+```bash
+semgrep --version
+# Or
+npx semgrep --version
+```
+
+## How It Works
+
+1. During `/qa`, the quality checks script detects if Semgrep is installed
+2. If installed, it runs Semgrep with stack-appropriate rulesets
+3. Findings are categorized by severity (critical, warning, info)
+4. Critical findings block the merge verdict (`AC_NOT_MET`)
+5. Warnings are noted but don't block merges
+
+## Default Rulesets
+
+Semgrep uses stack-specific rulesets for targeted analysis:
+
+| Stack | Rulesets Applied |
+|-------|------------------|
+| **Next.js** | p/typescript, p/javascript, p/react, p/security-audit, p/secrets |
+| **Astro** | p/typescript, p/javascript, p/security-audit, p/secrets |
+| **SvelteKit** | p/typescript, p/javascript, p/security-audit, p/secrets |
+| **Remix** | p/typescript, p/javascript, p/react, p/security-audit, p/secrets |
+| **Nuxt** | p/typescript, p/javascript, p/security-audit, p/secrets |
+| **Python** | p/python, p/django, p/flask, p/security-audit, p/secrets |
+| **Go** | p/golang, p/security-audit, p/secrets |
+| **Rust** | p/rust, p/security-audit, p/secrets |
+| **Generic** | p/security-audit, p/secrets |
+
+## Custom Rules
+
+You can add project-specific rules by creating `.sequant/semgrep-rules.yaml` in your project root.
+
+### Getting Started
+
+Copy the example template to your project:
+
+```bash
+# Copy the example template
+cp docs/examples/semgrep-rules.example.yaml .sequant/semgrep-rules.yaml
+```
+
+### Custom Rules File Location
+
+```
+your-project/
+├── .sequant/
+│   └── semgrep-rules.yaml    # Your custom rules
+├── src/
+└── package.json
+```
+
+### Example Custom Rules
+
+```yaml
+rules:
+  # Prevent console.log in production code
+  - id: no-console-log
+    pattern: console.log(...)
+    message: "Remove console.log before merging"
+    severity: WARNING
+    languages: [typescript, javascript]
+    paths:
+      exclude:
+        - "**/*.test.*"
+        - "**/__tests__/**"
+
+  # Require explicit return types on exported functions
+  - id: explicit-return-type
+    pattern: |
+      export function $FUNC(...): $RET { ... }
+    pattern-not: |
+      export function $FUNC(...): void { ... }
+    message: "Exported functions should have explicit return types"
+    severity: INFO
+    languages: [typescript]
+
+  # Detect potential SQL injection
+  - id: sql-injection-risk
+    patterns:
+      - pattern: $DB.query($SQL + ...)
+      - pattern: $DB.query(`...${...}...`)
+    message: "Potential SQL injection - use parameterized queries"
+    severity: ERROR
+    languages: [typescript, javascript]
+
+  # Prevent hardcoded API keys
+  - id: no-hardcoded-api-key
+    pattern-regex: "(api[_-]?key|apikey|secret[_-]?key)\\s*[:=]\\s*['\"][^'\"]{8,}['\"]"
+    message: "Don't hardcode API keys - use environment variables"
+    severity: ERROR
+    languages: [typescript, javascript, python]
+```
+
+### Rule Severity Levels
+
+| Severity | Verdict Impact | Description |
+|----------|----------------|-------------|
+| `ERROR` | **Blocking** | Critical issues that must be fixed |
+| `WARNING` | Non-blocking | Issues that should be reviewed |
+| `INFO` | Non-blocking | Style suggestions |
+
+## Running Semgrep Manually
+
+You can run Semgrep manually using the provided script:
+
+```bash
+# Scan entire project with auto-detected stack
+npx tsx scripts/semgrep-scan.ts
+
+# Scan only changed files (faster, recommended)
+npx tsx scripts/semgrep-scan.ts --changed-only
+
+# Scan specific directories
+npx tsx scripts/semgrep-scan.ts src/api/ src/lib/
+
+# Override detected stack
+npx tsx scripts/semgrep-scan.ts --stack python
+
+# Get JSON output
+npx tsx scripts/semgrep-scan.ts --json > semgrep-results.json
+```
+
+## Interpreting Results
+
+### Clean Output
+
+```
+## Static Analysis (Semgrep)
+
+✅ No security issues found
+```
+
+### Issues Found
+
+```
+## Static Analysis (Semgrep)
+
+❌ 1 critical finding(s)
+⚠️  2 warning(s)
+
+### ❌ Critical Issues
+
+- `src/api/users.ts:47` - Potential SQL injection (user input in query) (security.sql-injection)
+
+### ⚠️ Warnings
+
+- `src/utils/exec.ts:12` - Command injection risk (unsanitized shell arg) (security.command-injection)
+- `src/lib/logger.ts:8` - Remove console.log before merging (custom.no-console-log)
+```
+
+## Troubleshooting
+
+### Semgrep Not Running
+
+1. Check if Semgrep is installed: `semgrep --version`
+2. If not installed, install it or use `npx semgrep`
+3. Check for error messages in the quality checks output
+
+### False Positives
+
+If a rule produces false positives:
+
+1. Add a `# nosemgrep: rule-id` comment to ignore specific lines
+2. Create custom rules that exclude specific patterns
+3. Use path exclusions in your custom rules
+
+### Performance
+
+- Semgrep only scans changed files by default (via `--changed-only`)
+- Large codebases may take longer on first scan
+- Results are not cached between runs
+
+## Resources
+
+- [Semgrep Documentation](https://semgrep.dev/docs/)
+- [Semgrep Rule Registry](https://semgrep.dev/r)
+- [Writing Custom Rules](https://semgrep.dev/docs/writing-rules/overview/)
+- [Rule Syntax Reference](https://semgrep.dev/docs/writing-rules/rule-syntax/)

package/templates/skills/qa/scripts/quality-checks.sh

@@ -92,5 +92,59 @@ else
   echo "   npx not available, skipping security scan"
 fi
 
+# 9. Semgrep static analysis (optional - graceful skip if not installed)
+echo ""
+echo "🔍 Running Semgrep static analysis..."
+
+# Check if Semgrep is available
+semgrep_available=false
+if command -v semgrep &> /dev/null; then
+  semgrep_available=true
+  semgrep_cmd="semgrep"
+elif command -v npx &> /dev/null && npx semgrep --version &> /dev/null 2>&1; then
+  semgrep_available=true
+  semgrep_cmd="npx semgrep"
+fi
+
+if [[ "$semgrep_available" == "true" ]]; then
+  # Get changed files for targeted scan
+  changed_files=$(git diff main...HEAD --name-only | grep -E '\.(ts|tsx|js|jsx|py|go|rs)$' || true)
+
+  if [[ -n "$changed_files" ]]; then
+    # Run Semgrep with security rules on changed files
+    echo "   Scanning $(echo "$changed_files" | wc -l | xargs) changed file(s)..."
+
+    # Run with basic security rules, JSON output for reliable parsing
+    # Use --quiet to suppress progress
+    semgrep_output=$($semgrep_cmd --config p/security-audit --config p/secrets \
+      --quiet --no-git-ignore --json \
+      $changed_files 2>&1) || semgrep_exit=$?
+
+    if [[ -z "$semgrep_output" ]] || ! echo "$semgrep_output" | grep -q '"results"'; then
+      echo "   ✅ Semgrep: No security issues found"
+    else
+      # Count findings by severity from JSON output
+      # Semgrep JSON uses "severity":"ERROR" (uppercase) for critical, "WARNING" for warnings
+      critical_count=$(echo "$semgrep_output" | grep -o '"severity":"ERROR"' | wc -l | xargs)
+      warning_count=$(echo "$semgrep_output" | grep -o '"severity":"WARNING"' | wc -l | xargs)
+
+      if [[ "$critical_count" -gt 0 ]]; then
+        echo "   ❌ Semgrep: $critical_count critical finding(s) - REVIEW REQUIRED"
+      fi
+      if [[ "$warning_count" -gt 0 ]]; then
+        echo "   ⚠️  Semgrep: $warning_count warning(s)"
+      fi
+      if [[ "$critical_count" -eq 0 && "$warning_count" -eq 0 ]]; then
+        echo "   ✅ Semgrep: No security issues found"
+      fi
+    fi
+  else
+    echo "   No source files changed, skipping Semgrep scan"
+  fi
+else
+  echo "   ⚠️  Semgrep not installed (optional)"
+  echo "   Install with: pip install semgrep"
+fi
+
 echo ""
 echo "✅ Quality checks complete"