sequant 1.15.1 → 1.15.3

package/templates/skills/loop/SKILL.md

@@ -47,9 +47,9 @@ When invoked as `/loop <issue-number>`, your job is to:
 
 ### Step 1: Read Previous Phase Output
 
-```bash
-# Read the log file for this issue
-cat /tmp/claude-issue-<issue-number>.log
+Use the Read tool to read the log file for this issue:
+```
+Read(file_path="/tmp/claude-issue-<issue-number>.log")
 ```
 
 Parse the log to find:

package/templates/skills/qa/SKILL.md

@@ -369,7 +369,7 @@ fi
 
 **If no verification evidence exists:**
 1. Prompt: "Script changes detected but no execution verification found. Run `/verify <issue> --command \"<test command>\"` before READY_FOR_MERGE verdict."
-2. Do NOT give `READY_FOR_MERGE` verdict until verification is complete
+2. Do NOT give `READY_FOR_MERGE` verdict until verification is complete (unless an approved override applies — see Section 9a)
 3. Verdict should be `AC_MET_BUT_NOT_A_PLUS` with note about missing verification
 
 **Why this matters:**
@@ -389,6 +389,59 @@ fi
 /qa 558  # Re-run, now sees verification, can give READY_FOR_MERGE
 ```
 
+### 9a. Script Verification Override
+
+In some cases, `/verify` execution can be safely skipped when script changes are purely cosmetic or have no runtime impact. **Overrides require explicit justification and risk assessment.**
+
+**Override Format (REQUIRED when skipping /verify):**
+
+```markdown
+### Script Verification Override
+
+**Requirement:** `/verify` before READY_FOR_MERGE
+**Override:** Yes
+**Justification:** [One of the approved categories below]
+**Risk Assessment:** [None/Low/Medium]
+```
+
+**Approved Override Categories:**
+
+| Category | Example | Risk |
+|----------|---------|------|
+| Syntax-only refactor | `catch (error)` → `catch` | None |
+| Comment/documentation changes | Adding JSDoc, updating comments | None |
+| Type annotation additions | Adding `: string`, `: number` | None |
+| Import reorganization | Sorting imports, removing unused | None |
+| Variable rename (no logic change) | `foo` → `bar` with no behavioral change | Low |
+| Dead code removal | Removing unreachable branches | Low |
+
+**NOT Approved for Override (always require /verify):**
+
+| Category | Example | Why |
+|----------|---------|-----|
+| Logic changes | Modified conditionals, new branches | Runtime behavior changes |
+| New functionality | Added functions, new exports | Must verify execution |
+| Dependency changes | Updated imports from new packages | May affect runtime |
+| Error handling changes | Modified catch blocks, new try/catch | Failure paths change |
+| Configuration changes | Modified env vars, config parsing | Environment-dependent |
+
+**Risk Assessment Definitions:**
+
+| Level | Meaning | Criteria |
+|-------|---------|----------|
+| **None** | Zero runtime impact | Change is invisible at runtime (comments, types, syntax) |
+| **Low** | Negligible runtime impact | Change is cosmetic (rename, dead code) with no logical effect |
+| **Medium** | Possible runtime impact | Change touches executable code but appears safe — **should NOT be overridden** |
+
+**Override Decision Flow:**
+
+1. Check if change matches an approved category → If no, `/verify` is required
+2. Assess risk level → If Medium or higher, `/verify` is required
+3. Document override using the format above in the QA output
+4. Include override in the GitHub issue comment for audit trail
+
+**CRITICAL:** When in doubt, run `/verify`. Overrides are for clear-cut cases only. If you need to argue that a change is safe, it probably needs verification.
+
 ---
 
 ## Output Verification
@@ -399,6 +452,7 @@ fi
 - [ ] **Verdict** - One of: READY_FOR_MERGE, AC_MET_BUT_NOT_A_PLUS, AC_NOT_MET
 - [ ] **Quality Metrics** - Type issues, deleted tests, files changed, additions/deletions
 - [ ] **Code Review Findings** - Strengths, issues, suggestions
+- [ ] **Script Verification Override** - Included if scripts/CLI modified AND /verify was skipped (with justification and risk assessment)
 - [ ] **Documentation Check** - README/docs updated if feature adds new functionality
 - [ ] **Next Steps** - Clear, actionable recommendations
 
@@ -447,6 +501,17 @@ You MUST include these sections:
 
 ---
 
+### Script Verification Override
+
+[Include if scripts/CLI modified AND /verify was skipped, otherwise omit this section]
+
+**Requirement:** `/verify` before READY_FOR_MERGE
+**Override:** Yes
+**Justification:** [Approved category from Section 9a]
+**Risk Assessment:** [None/Low/Medium]
+
+---
+
 ### Verdict: [READY_FOR_MERGE | AC_MET_BUT_NOT_A_PLUS | AC_NOT_MET]
 
 [Explanation of verdict]

package/templates/skills/qa/references/code-review-checklist.md

@@ -51,16 +51,15 @@ If project uses a database with access controls:
 
 ## Integration Check
 
-Verify new exports are imported somewhere:
-```bash
+Verify new exports are imported somewhere using the Grep tool:
+```
+# 1. Get new files from git
 new_files=$(git diff main...HEAD --name-only --diff-filter=A | grep -E "\.(ts|tsx)$" || true)
-for file in $new_files; do
-  exports=$(grep -oE "export (const|function|class|type|interface) ([A-Za-z_][A-Za-z0-9_]*)" "$file" | awk '{print $3}')
-  for exp in $exports; do
-    import_count=$(grep -r "import.*$exp" --include="*.ts" --include="*.tsx" . | grep -v "$file" | wc -l | xargs)
-    if [[ $import_count -eq 0 ]]; then
-      echo "⚠️ '$exp' exported from $file but never imported"
-    fi
-  done
-done
+
+# 2. For each new file, use Grep to find exports:
+#    Grep(pattern="export (const|function|class|type|interface)", path="<file>", output_mode="content")
+
+# 3. For each export, use Grep to check if it's imported anywhere:
+#    Grep(pattern="import.*<export_name>", glob="*.{ts,tsx}")
+#    If no matches (excluding the source file), flag as unused export
 ```

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

@@ -600,6 +600,22 @@ if [[ $hit_count -gt 0 ]]; then
 fi
 echo ""
 
+# Write structured cache metrics JSON for sequant observability (AC-7)
+# This file is read by run.ts to populate PhaseLog.cacheMetrics
+CACHE_METRICS_DIR=".sequant/.cache/qa"
+mkdir -p "$CACHE_METRICS_DIR"
+
+# Build JSON with per-check status
+CACHE_JSON="{\"hits\":$hit_count,\"misses\":$miss_count,\"skipped\":$skip_count,\"checks\":{"
+first=true
+for check in "type-safety" "deleted-tests" "scope" "size" "security" "semgrep" "build"; do
+  $first || CACHE_JSON+=","
+  CACHE_JSON+="\"$check\":\"${CACHE_STATUS[$check]:-MISS}\""
+  first=false
+done
+CACHE_JSON+="}}"
+echo "$CACHE_JSON" > "$CACHE_METRICS_DIR/cache-metrics.json"
+
 echo "✅ Quality checks complete"
 
 # Exit with build verification result if it indicates a problem

package/templates/skills/security-review/references/security-checklists.md

@@ -8,8 +8,11 @@ Detailed checklists for each security domain, used by the `/security-review` ski
 **Requirement:** Passwords must use bcrypt/argon2 with appropriate cost factor.
 
 **How to Verify:**
-```bash
-grep -r "bcrypt\|argon2\|hashPassword" lib/ app/
+
+Use the Grep tool for content search:
+```
+Grep(pattern="bcrypt|argon2|hashPassword", path="lib/")
+Grep(pattern="bcrypt|argon2|hashPassword", path="app/")
 ```
 
 **Good:**
@@ -27,8 +30,10 @@ const hash = crypto.createHash('sha256').update(password).digest('hex')
 **Requirement:** Session tokens must be cryptographically random.
 
 **How to Verify:**
-```bash
-grep -r "crypto.randomBytes\|uuid\|nanoid" lib/auth/
+
+Use the Grep tool for content search:
+```
+Grep(pattern="crypto.randomBytes|uuid|nanoid", path="lib/auth/")
 ```
 
 **Good:**
@@ -45,8 +50,11 @@ const token = Date.now().toString(36)
 **Requirement:** Sessions must expire within appropriate timeframe.
 
 **How to Verify:**
-```bash
-grep -r "maxAge\|expires\|TTL" lib/auth/ app/api/auth/
+
+Use the Grep tool for content search:
+```
+Grep(pattern="maxAge|expires|TTL", path="lib/auth/")
+Grep(pattern="maxAge|expires|TTL", path="app/api/auth/")
 ```
 
 **Good:** 15-60 minutes for sensitive, 1-7 days for general.
@@ -64,8 +72,11 @@ grep -r "maxAge\|expires\|TTL" lib/auth/ app/api/auth/
 **Requirement:** Reset tokens must be single-use and time-limited.
 
 **How to Verify:**
-```bash
-grep -r "resetToken\|passwordReset" lib/ app/
+
+Use the Grep tool for content search:
+```
+Grep(pattern="resetToken|passwordReset", path="lib/")
+Grep(pattern="resetToken|passwordReset", path="app/")
 ```
 
 **Good:** Token expires in 1 hour, deleted after use.
@@ -76,8 +87,11 @@ grep -r "resetToken\|passwordReset" lib/ app/
 **Requirement:** Failed login attempts must be rate-limited.
 
 **How to Verify:**
-```bash
-grep -r "rateLimit\|loginAttempts\|throttle" lib/ app/api/auth/
+
+Use the Grep tool for content search:
+```
+Grep(pattern="rateLimit|loginAttempts|throttle", path="lib/")
+Grep(pattern="rateLimit|loginAttempts|throttle", path="app/api/auth/")
 ```
 
 **Good:** 5 attempts per 15 minutes.
@@ -86,8 +100,10 @@ grep -r "rateLimit\|loginAttempts\|throttle" lib/ app/api/auth/
 **Requirement:** Password comparison must be constant-time.
 
 **How to Verify:**
-```bash
-grep -r "timingSafeEqual\|bcrypt.compare" lib/auth/
+
+Use the Grep tool for content search:
+```
+Grep(pattern="timingSafeEqual|bcrypt.compare", path="lib/auth/")
 ```
 
 **Good:**
@@ -116,8 +132,11 @@ if (input === password) // Direct comparison leaks timing info
 **Requirement:** Every sensitive endpoint must check authentication.
 
 **How to Verify:**
-```bash
-grep -r "requireAuth\|getServerSession\|authenticate" app/api/ app/admin/
+
+Use the Grep tool for content search:
+```
+Grep(pattern="requireAuth|getServerSession|authenticate", path="app/api/")
+Grep(pattern="requireAuth|getServerSession|authenticate", path="app/admin/")
 ```
 
 **Good:** Middleware checks auth before route handler.
@@ -128,8 +147,11 @@ grep -r "requireAuth\|getServerSession\|authenticate" app/api/ app/admin/
 **Requirement:** Role checks must happen before privileged actions.
 
 **How to Verify:**
-```bash
-grep -r "role\|isAdmin\|hasPermission" lib/ app/
+
+Use the Grep tool for content search:
+```
+Grep(pattern="role|isAdmin|hasPermission", path="lib/")
+Grep(pattern="role|isAdmin|hasPermission", path="app/")
 ```
 
 **Good:**
@@ -173,8 +195,11 @@ const item = await db.items.findUnique({ where: { id: itemId } })
 **Requirement:** Admin actions must be logged for audit.
 
 **How to Verify:**
-```bash
-grep -r "audit\|logAction\|createAuditLog" lib/ app/admin/
+
+Use the Grep tool for content search:
+```
+Grep(pattern="audit|logAction|createAuditLog", path="lib/")
+Grep(pattern="audit|logAction|createAuditLog", path="app/admin/")
 ```
 
 **Good:**
@@ -190,8 +215,11 @@ await logAuditEvent({ action: 'approve_item', actor: userId, target: itemId })
 **Requirement:** All inputs must be validated with schemas.
 
 **How to Verify:**
-```bash
-grep -r "z\.\|zod\|yup\|joi" lib/validations/ app/api/
+
+Use the Grep tool for content search:
+```
+Grep(pattern="z\\.|zod|yup|joi", path="lib/validations/")
+Grep(pattern="z\\.|zod|yup|joi", path="app/api/")
 ```
 
 **Good:**
@@ -216,8 +244,11 @@ const { name } = req.body // No validation
 **Requirement:** Queries must use parameterized statements.
 
 **How to Verify:**
-```bash
-grep -r "raw\|execute\|query" lib/ app/
+
+Use the Grep tool for content search:
+```
+Grep(pattern="raw|execute|query", path="lib/")
+Grep(pattern="raw|execute|query", path="app/")
 ```
 
 **Good:**
@@ -237,16 +268,22 @@ db.query(`SELECT * FROM items WHERE id = ${itemId}`)
 **Requirement:** Public endpoints must be rate-limited.
 
 **How to Verify:**
-```bash
-grep -r "rateLimit\|Ratelimit" middleware/ lib/
+
+Use the Grep tool for content search:
+```
+Grep(pattern="rateLimit|Ratelimit", path="middleware/")
+Grep(pattern="rateLimit|Ratelimit", path="lib/")
 ```
 
 ### API-5: CORS Configuration
 **Requirement:** CORS must be properly configured.
 
 **How to Verify:**
-```bash
-grep -r "cors\|Access-Control" next.config.js middleware/
+
+Use the Grep tool for content search:
+```
+Grep(pattern="cors|Access-Control", path="next.config.js")
+Grep(pattern="cors|Access-Control", path="middleware/")
 ```
 
 **Good:** Specific origins allowed.
@@ -274,8 +311,11 @@ return { error: err.message, stack: err.stack }
 **Requirement:** Uploads must validate type, size, and name.
 
 **How to Verify:**
-```bash
-grep -r "upload\|multipart\|formData" app/api/ lib/
+
+Use the Grep tool for content search:
+```
+Grep(pattern="upload|multipart|formData", path="app/api/")
+Grep(pattern="upload|multipart|formData", path="lib/")
 ```
 
 **Good:**
@@ -314,8 +354,11 @@ if (file.size > 5 * 1024 * 1024) throw Error
 **Requirement:** Logs must not contain sensitive data.
 
 **How to Verify:**
-```bash
-grep -r "console.log\|logger" lib/ app/ | head -20
+
+Use the Grep tool for content search:
+```
+Grep(pattern="console.log|logger", path="lib/", head_limit=20)
+Grep(pattern="console.log|logger", path="app/", head_limit=20)
 ```
 
 **Bad:**
@@ -338,8 +381,11 @@ console.log('User login:', { email, password })
 **Requirement:** Secrets must be in env vars, not code.
 
 **How to Verify:**
-```bash
-grep -r "process.env" lib/ app/ | head -10
+
+Use the Grep tool for content search:
+```
+Grep(pattern="process.env", path="lib/", head_limit=10)
+Grep(pattern="process.env", path="app/", head_limit=10)
 ```
 
 **Good:** API keys in `.env.local`, read via `process.env`.
@@ -350,8 +396,12 @@ grep -r "process.env" lib/ app/ | head -10
 **Requirement:** No secrets committed to repository.
 
 **How to Verify:**
-```bash
-grep -ri "password\|secret\|apikey\|api_key" --include="*.ts" --include="*.tsx" . | grep -v "process.env"
+
+Use the Grep tool for content search (filter results excluding process.env):
+```
+Grep(pattern="password|secret|apikey|api_key", glob="*.ts", -i=true)
+Grep(pattern="password|secret|apikey|api_key", glob="*.tsx", -i=true)
+# Then manually filter out lines containing "process.env"
 ```
 
 ### INFRA-3: Dependencies Up to Date
@@ -366,8 +416,11 @@ npm audit
 **Requirement:** Content Security Policy should be configured.
 
 **How to Verify:**
-```bash
-grep -r "Content-Security-Policy\|CSP" next.config.js middleware/
+
+Use the Grep tool for content search:
+```
+Grep(pattern="Content-Security-Policy|CSP", path="next.config.js")
+Grep(pattern="Content-Security-Policy|CSP", path="middleware/")
 ```
 
 ### INFRA-5: Security Headers

package/templates/skills/solve/SKILL.md

@@ -106,7 +106,9 @@ gh issue view <issue-number> --json body --jq '.body' | grep -iE "(feature/|bran
 gh issue view <issue-number> --json labels --jq '.labels[].name' | grep -iE "(dashboard|feature-|epic-)"
 
 # Check if project has defaultBase configured
-cat .sequant/settings.json 2>/dev/null | jq -r '.run.defaultBase // empty'
+# Use the Read tool to check project settings
+Read(file_path=".sequant/settings.json")
+# Extract .run.defaultBase from the JSON
 ```
 
 **Recommend `--base <branch>` when:**

package/templates/skills/spec/SKILL.md

@@ -198,8 +198,10 @@ console.log(formatACLintResults(lintResults));
 **You MUST spawn sub-agents for context gathering.** Do NOT explore the codebase inline with Glob/Grep commands. Sub-agents provide parallel execution, better context isolation, and consistent reporting.
 
 **Check agent execution mode first:**
-```bash
-parallel=$(cat .sequant/settings.json 2>/dev/null | jq -r '.agents.parallel // false')
+Use the Read tool to check project settings:
+```
+Read(file_path=".sequant/settings.json")
+# Parse JSON and extract agents.parallel (default: false)
 ```
 
 #### If parallel mode enabled:
@@ -237,8 +239,10 @@ Before creating the implementation plan, check if a custom base branch should be
    ```
 
 3. **Check if project has defaultBase configured**:
-   ```bash
-   cat .sequant/settings.json 2>/dev/null | jq -r '.run.defaultBase // empty'
+   Use the Read tool to check settings:
+   ```
+   Read(file_path=".sequant/settings.json")
+   # Extract .run.defaultBase from JSON
    ```
 
 4. **If feature branch context detected**, include in plan output: