sequant 2.6.2 → 2.8.0

package/templates/skills/loop/SKILL.md

@@ -42,6 +42,30 @@ When invoked as `/loop <issue-number>`, your job is to:
 4. Re-run validation until quality gates pass
 5. Exit when `READY_FOR_MERGE` or max iterations reached
 
+## Orchestration Context
+
+When running as part of an orchestrated workflow (e.g., `sequant run` or `/fullsolve`), this skill receives environment variables that indicate the orchestration context:
+
+| Environment Variable | Description | Example Value |
+|---------------------|-------------|---------------|
+| `SEQUANT_ORCHESTRATOR` | The orchestrator invoking this skill | `sequant-run` |
+| `SEQUANT_PHASE` | Current phase in the workflow | `loop` |
+| `SEQUANT_ISSUE` | Issue number being processed | `123` |
+| `SEQUANT_WORKTREE` | Path to the feature worktree | `/path/to/worktrees/feature/...` |
+
+**Behavior when orchestrated (SEQUANT_ORCHESTRATOR is set):**
+
+1. **Use provided worktree** - Work in `SEQUANT_WORKTREE` path directly
+2. **Use `SEQUANT_ISSUE`** - Skip issue number parsing from invocation
+3. **Reduce GitHub comment frequency** - Defer updates to orchestrator
+4. **Trust issue context** - Orchestrator has already validated issue
+
+**Behavior when standalone (SEQUANT_ORCHESTRATOR is NOT set):**
+
+- Locate worktree from issue number
+- Post progress comments to GitHub
+- Fetch issue context if needed
+
 ## Invocation
 
 - `/loop 123` - Parse log for issue #123, fix issues, re-validate
@@ -50,12 +74,66 @@ When invoked as `/loop <issue-number>`, your job is to:
 
 ### Step 1: Read Previous Phase Output
 
+**The source of findings depends on whether you're running in orchestrated or standalone mode.**
+
+#### Step 1A: Orchestrated Mode (SEQUANT_ORCHESTRATOR is set)
+
+When `SEQUANT_ORCHESTRATOR` is set, read QA findings from the GitHub issue comments instead of a log file:
+
+```bash
+# Check if we're in orchestrated mode
+if [[ -n "$SEQUANT_ORCHESTRATOR" ]]; then
+  echo "Orchestrated mode detected (orchestrator: $SEQUANT_ORCHESTRATOR)"
+
+  # Use SEQUANT_ISSUE if provided, otherwise parse from invocation
+  ISSUE_NUMBER="${SEQUANT_ISSUE:-<issue-number>}"
+
+  # Fetch QA findings from issue comments (use startswith to avoid matching comments that reference QA format)
+  gh issue view "$ISSUE_NUMBER" --json comments -q '.comments[] | select(.body | startswith("## QA Review for Issue")) | .body' | tail -1
+fi
+```
+
+**How to identify QA comments:**
+
+| Pattern | Meaning |
+|---------|---------|
+| `## QA Review for Issue #N` | QA phase comment header |
+| `### Verdict:` | Contains AC_NOT_MET, AC_MET_BUT_NOT_A_PLUS, etc. |
+| `### AC Coverage` | Table with MET/NOT_MET/PARTIALLY_MET statuses |
+| `### Required Fixes` or `### Recommendations` | Actionable items to fix |
+
+**Parsing QA comment:**
+```bash
+# Extract verdict from QA comment
+verdict=$(echo "$qa_comment" | grep -oE "Verdict:\s*\w+" | head -1 | awk '{print $2}' || true)
+
+# Extract NOT_MET AC items
+not_met_acs=$(echo "$qa_comment" | grep -E "NOT_MET|PARTIALLY_MET" || true)
+
+# Extract recommendations section
+recommendations=$(echo "$qa_comment" | sed -n '/### Required Fixes/,/###/p' | head -n -1)
+```
+
+**If no QA comment found in orchestrated mode:**
+1. Log a clear error: `"Warning: No QA comment found in issue #N"`
+2. Fall back to Step 1B (log file) as a recovery mechanism
+3. If log file also doesn't exist, exit with error
+
+#### Step 1B: Standalone Mode (no SEQUANT_ORCHESTRATOR)
+
+When running standalone (interactive `/loop` invocation), read from the log file:
+
 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:
+**If log file doesn't exist:**
+- Error: `"Log file not found at /tmp/claude-issue-<N>.log. Please run /spec, /exec, /test, or /qa first."`
+
+#### Parsing Findings (Both Modes)
+
+Parse the output (from comment or log file) to find:
 - **Last phase executed:** `/test` or `/qa`
 - **Verdict:** `READY_FOR_MERGE`, `AC_MET_BUT_NOT_A_PLUS`, `NEEDS_VERIFICATION`,
   or `AC_NOT_MET`
@@ -102,6 +180,12 @@ Extract:
 
 ### Step 4: Locate Feature Worktree
 
+**If orchestrated (SEQUANT_WORKTREE is set):**
+- Use the provided worktree path directly: `cd $SEQUANT_WORKTREE`
+- Skip the lookup steps below
+
+**If standalone:**
+
 Find the worktree for this issue:
 ```bash
 git worktree list | grep -E "feature.*<issue-number>" || true
@@ -365,7 +449,21 @@ For each iteration, output:
 
 ## Error Handling
 
-**If log file doesn't exist:**
+**If orchestrated but no QA comment found:**
+```
+Warning: No QA comment found in issue #<N>
+Attempting fallback to log file...
+```
+
+If fallback also fails:
+```
+Error: No QA findings available.
+- No QA comment found in issue #<N>
+- Log file not found at /tmp/claude-issue-<N>.log
+Please run /qa <N> first.
+```
+
+**If log file doesn't exist (standalone mode):**
 ```
 Error: Log file not found at /tmp/claude-issue-<N>.log
 Please run /spec, /exec, /test, or /qa first.

package/templates/skills/qa/SKILL.md

@@ -1085,6 +1085,30 @@ skill_modified=$(git diff main...HEAD --name-only | grep -E "^\.(claude/skills|s
 ```
 If skill files are modified, the quality-checks.sh script automatically runs the three-directory sync check (section 12). If divergence is detected, this blocks `READY_FOR_MERGE` — verdict becomes `AC_MET_BUT_NOT_A_PLUS` with a note to run `npx tsx scripts/check-skill-sync.ts --fix`.
 
+#### Turn-Capped Checks → Inconclusive (not a phase failure)
+
+A spawned quality-check sub-agent runs under a `maxTurns` cap (live on every agent since #484). When an agent hits that cap, its work is **partial**, not failed — the driver returns it flagged `capped: true` and warns rather than erroring (#733).
+
+**How to recognize a turn-capped check:** the sub-agent's reported output is truncated mid-analysis, ends without a verdict, or explicitly notes it ran out of turns (look for `error_max_turns`, "turn cap", or "Returning partial results" in its output).
+
+**How to handle it — do NOT fail the whole QA phase on a cap alone:**
+
+- Mark that single check **⚠️ Inconclusive** in the QA summary, with a one-line reason (`hit turn cap — partial analysis`).
+- Use whatever partial findings the capped agent *did* surface; do not discard them.
+- Let the **other** checks proceed and contribute to the verdict normally.
+- If a capped check leaves an AC genuinely unverified, the verdict is `NEEDS_VERIFICATION` for that AC — never a hard `AC_NOT_MET` justified solely by the cap.
+- Surface inconclusive checks prominently so a human can re-run that check (e.g. with a higher cap) rather than silently treating the cap as a pass.
+
+```markdown
+### Quality Checks
+
+| Check | Status | Notes |
+|-------|--------|-------|
+| Type safety | ✅ Pass | 0 issues |
+| Scope/size | ⚠️ Inconclusive | hit turn cap — partial analysis, re-run recommended |
+| Security | ✅ Pass | 0 critical |
+```
+
 See [quality-gates.md](references/quality-gates.md) for detailed verdict synthesis.
 
 ### Using MCP Tools (Optional)

package/templates/skills/qa/references/anti-pattern-detection.md

@@ -0,0 +1,285 @@
+# Anti-Pattern Detection
+
+## Purpose
+
+Lightweight pattern-matching sanity checks to catch issues that experts would flag immediately. These checks complement code review by automating detection of common mistakes.
+
+## Part 1: New Dependency Audit
+
+### When to Run
+
+Run dependency audit when `package.json` is modified:
+
+```bash
+# Check if package.json was modified
+pkg_modified=$(git diff main...HEAD --name-only | grep -E "^package\.json$" | head -1)
+if [[ -n "$pkg_modified" ]]; then
+  echo "package.json modified - running dependency audit"
+fi
+```
+
+### Detecting New Dependencies
+
+```bash
+# Get new dependencies (added in this branch)
+git diff main...HEAD -- package.json | grep '^\+.*":' | grep -v '^\+\+\+' | sed 's/.*"\([^"]*\)".*/\1/' | grep -v -E '^(@types/|version|name|description|scripts|devDependencies|dependencies|peerDependencies)$'
+```
+
+### Audit Criteria
+
+| Flag | Threshold | Detection Method | Risk Level |
+|------|-----------|------------------|------------|
+| Low downloads | <1,000/week | `npm view <pkg> --json \| jq '.downloads'` | ⚠️ Medium |
+| Stale | No updates 12+ months | `npm view <pkg> time.modified` | ⚠️ Medium |
+| License risk | UNLICENSED, GPL in MIT project | `npm view <pkg> license` | ❌ High |
+| Size concern | >100kb for utility | `npm view <pkg> dist.unpackedSize` | ⚠️ Low |
+| Security advisory | Known vulnerabilities | `npm audit --json` | ❌ High |
+
+### Audit Commands
+
+```bash
+# Get package metadata (run for each new dependency)
+pkg="<package-name>"
+
+# Weekly downloads (requires npm API)
+downloads=$(curl -s "https://api.npmjs.org/downloads/point/last-week/$pkg" | jq '.downloads // 0')
+
+# Last update date
+last_update=$(npm view "$pkg" time.modified 2>/dev/null)
+
+# License
+license=$(npm view "$pkg" license 2>/dev/null)
+
+# Unpacked size (in bytes)
+size=$(npm view "$pkg" dist.unpackedSize 2>/dev/null)
+
+# Security check (all dependencies)
+npm audit --json 2>/dev/null | jq '.vulnerabilities | length'
+```
+
+### Output Format
+
+```markdown
+### Dependency Audit
+
+| Package | Downloads/wk | Last Update | License | Size | Flags |
+|---------|--------------|-------------|---------|------|-------|
+| foo-pkg | 500 | 2023-01-15 | MIT | 45kb | ⚠️ Low downloads, ⚠️ Stale |
+| bar-lib | 50,000 | 2024-12-01 | Apache-2.0 | 120kb | ⚠️ Size |
+
+**Security Audit:** 0 vulnerabilities found
+
+**Flagged Dependencies:**
+1. `foo-pkg` - Low downloads (<1,000/week) and stale (12+ months)
+   - **Risk:** Unmaintained packages may have unpatched vulnerabilities
+   - **Suggestion:** Consider alternative with active maintenance or vendor the code
+```
+
+### Verdict Impact
+
+| Finding | Verdict Impact |
+|---------|----------------|
+| Low downloads only | Note in QA, no verdict change |
+| Stale only | Note in QA, no verdict change |
+| Security vulnerability (moderate+) | `AC_NOT_MET` (blocker) |
+| License incompatibility | `AC_NOT_MET` (blocker) |
+| Multiple flags on same package | `AC_MET_BUT_NOT_A_PLUS` |
+
+---
+
+## Part 2: Code Pattern Checks
+
+### Anti-Pattern Detection Matrix
+
+| Category | Pattern | Detection | Suggestion | Risk |
+|----------|---------|-----------|------------|------|
+| **Performance** | N+1 query (`await` in loop) | `for.*await\|\.forEach.*await` | Use batch query or `Promise.all` | ⚠️ Medium |
+| **Performance** | Unbounded loop | `while.*true\|for.*;;` without break limit | Add iteration limit | ⚠️ Medium |
+| **Performance** | Sync file ops in async context | `fs\.readFileSync\|fs\.writeFileSync` | Use async fs methods | ⚠️ Low |
+| **Error Handling** | Empty catch block | `catch.*\{\s*\}` | Log or rethrow | ⚠️ Medium |
+| **Error Handling** | Swallowed error | `catch.*\{\s*//` | Handle or rethrow | ⚠️ Medium |
+| **Error Handling** | Unhandled promise | `\.then\(.*\)[^.]` without `.catch` | Add `.catch()` or use try/catch | ⚠️ Medium |
+| **Security** | Hardcoded secret | `(api[_-]?key\|secret\|password)\s*[:=]\s*['"][^'"]+['"]` | Use env variable | ❌ High |
+| **Security** | SQL concatenation | `\+.*SELECT\|SELECT.*\+\|'.*\$\{.*\}.*SELECT` | Use parameterized query | ❌ High |
+| **Security** | eval usage | `eval\(` | Remove eval, use safe alternative | ❌ High |
+| **Security** | Server binds all interfaces | `.listen(port)` without explicit host | Bind to `127.0.0.1` for local-only servers | ❌ High |
+| **Memory** | Uncleared interval | `setInterval\(` without corresponding `clearInterval` | Clear in cleanup | ⚠️ Medium |
+| **Memory** | Uncleared timeout | `setTimeout\(` in component without cleanup | Clear in useEffect cleanup | ⚠️ Low |
+| **A11y** | Image without alt | `<img[^>]*(?!alt=)[^>]*>` | Add descriptive alt | ⚠️ Low |
+| **A11y** | Click handler without keyboard | `onClick=\{` without `onKeyDown` | Add keyboard handler | ⚠️ Low |
+
+### Detection Commands
+
+```bash
+# Run on changed files only
+changed_files=$(git diff main...HEAD --name-only | grep -E '\.(ts|tsx|js|jsx)$')
+
+# N+1 query pattern (await in loop)
+grep -n -E 'for\s*\([^)]*\)\s*\{[^}]*await|\.forEach\([^)]*async' $changed_files 2>/dev/null
+
+# Empty catch block
+grep -n -E 'catch\s*\([^)]*\)\s*\{\s*\}' $changed_files 2>/dev/null
+
+# Hardcoded secrets (case insensitive)
+grep -ni -E '(api[_-]?key|secret|password|token)\s*[:=]\s*['"'"'"][^'"'"'"]+['"'"'"]' $changed_files 2>/dev/null | grep -v -E '(\.env|example|test|mock|placeholder)'
+
+# SQL concatenation
+grep -n -E "(\+\s*['\"].*SELECT|SELECT.*['\"].*\+|\`.*\$\{.*\}.*SELECT)" $changed_files 2>/dev/null
+
+# Server binding to all interfaces (0.0.0.0)
+grep -n -E '\.listen\(\s*(port|[0-9]+)\s*[,)]' $changed_files 2>/dev/null | grep -v -E '127\.0\.0\.1|localhost'
+
+# Uncleared intervals (check for setInterval without corresponding clear)
+for f in $changed_files; do
+  intervals=$(grep -c 'setInterval(' "$f" 2>/dev/null || echo 0)
+  clears=$(grep -c 'clearInterval(' "$f" 2>/dev/null || echo 0)
+  if [[ $intervals -gt $clears ]]; then
+    echo "$f: $intervals setInterval calls, only $clears clearInterval calls"
+  fi
+done
+```
+
+### Output Format
+
+```markdown
+### Code Pattern Analysis
+
+| File:Line | Category | Pattern | Suggestion |
+|-----------|----------|---------|------------|
+| `src/api/users.ts:45` | Performance | N+1 query | Use `Promise.all` for batch fetching |
+| `src/utils/config.ts:12` | Error Handling | Empty catch | Log error or rethrow |
+| `src/components/List.tsx:89` | Memory | Uncleared interval | Add `clearInterval` in cleanup |
+
+**Critical Issues:** 0
+**Warnings:** 3
+
+**Details:**
+
+1. **N+1 Query** at `src/api/users.ts:45`
+   ```typescript
+   // Current (N+1)
+   for (const id of userIds) {
+     await fetchUser(id);  // Makes N requests
+   }
+
+   // Suggested
+   await Promise.all(userIds.map(id => fetchUser(id)));
+   // Or use batch endpoint
+   await fetchUsers(userIds);
+   ```
+
+2. **Empty Catch** at `src/utils/config.ts:12`
+   ```typescript
+   // Current
+   try { ... } catch (e) { }
+
+   // Suggested
+   try { ... } catch (e) {
+     console.error('Config load failed:', e);
+     // or rethrow: throw e;
+   }
+   ```
+```
+
+### Verdict Impact
+
+| Finding | Verdict Impact |
+|---------|----------------|
+| Performance warnings | Note in QA, no verdict change |
+| Empty catch blocks | `AC_MET_BUT_NOT_A_PLUS` |
+| Security issues (secrets, SQL injection) | `AC_NOT_MET` (blocker) |
+| Uncleared intervals/timeouts | `AC_MET_BUT_NOT_A_PLUS` |
+| A11y issues | Note in QA, no verdict change |
+
+---
+
+## Part 3: Integration with QA Workflow
+
+### When to Run
+
+1. **Dependency Audit:** Only when `package.json` is modified
+2. **Code Pattern Checks:** Always run on changed `.ts/.tsx/.js/.jsx` files
+
+### Execution Order
+
+```
+1. Standard quality checks (type safety, deleted tests, scope)
+2. Dependency audit (if package.json modified)
+3. Code pattern checks
+4. Test quality review (if test files modified)
+5. Execution evidence (if scripts/CLI modified)
+```
+
+### Combined Output Section
+
+```markdown
+### Anti-Pattern Detection
+
+#### Dependency Audit
+[Include if package.json modified, otherwise: "N/A - No dependency changes"]
+
+#### Code Patterns
+[Always include for code changes]
+
+**Summary:**
+- Dependencies flagged: X
+- Code patterns flagged: Y
+- Critical issues: Z (blockers)
+```
+
+---
+
+## Appendix: Full Detection Script
+
+For automation, this script can be run to check all patterns:
+
+```bash
+#!/bin/bash
+# anti-pattern-check.sh
+
+set -e
+
+echo "=== Anti-Pattern Detection ==="
+
+# Get changed files
+CHANGED_TS=$(git diff main...HEAD --name-only | grep -E '\.(ts|tsx|js|jsx)$' || true)
+PKG_CHANGED=$(git diff main...HEAD --name-only | grep -E '^package\.json$' || true)
+
+# 1. Dependency Audit
+if [[ -n "$PKG_CHANGED" ]]; then
+  echo ""
+  echo "## Dependency Audit"
+  # Get new deps
+  NEW_DEPS=$(git diff main...HEAD -- package.json | grep '^\+.*":' | grep -v '^\+\+\+' | sed 's/.*"\([^"]*\)".*/\1/' | grep -v -E '^(@types/|version|name|description|scripts|devDependencies|dependencies|peerDependencies|engines|repository|author|license|bugs|homepage|main|module|types)$' || true)
+
+  if [[ -n "$NEW_DEPS" ]]; then
+    echo "New dependencies detected:"
+    for dep in $NEW_DEPS; do
+      echo "  - $dep"
+    done
+  else
+    echo "No new dependencies added"
+  fi
+fi
+
+# 2. Code Pattern Checks
+if [[ -n "$CHANGED_TS" ]]; then
+  echo ""
+  echo "## Code Pattern Checks"
+
+  echo ""
+  echo "### N+1 Queries (await in loop):"
+  grep -n -E 'for\s*\([^)]*\)\s*\{[^}]*await|\.forEach\([^)]*async' $CHANGED_TS 2>/dev/null || echo "  None found"
+
+  echo ""
+  echo "### Empty Catch Blocks:"
+  grep -n -E 'catch\s*\([^)]*\)\s*\{\s*\}' $CHANGED_TS 2>/dev/null || echo "  None found"
+
+  echo ""
+  echo "### Potential Hardcoded Secrets:"
+  grep -ni -E '(api[_-]?key|secret|password|token)\s*[:=]\s*['"'"'"][^'"'"'"]+['"'"'"]' $CHANGED_TS 2>/dev/null | grep -v -E '(\.env|example|test|mock|placeholder|process\.env)' || echo "  None found"
+fi
+
+echo ""
+echo "=== End Anti-Pattern Detection ==="
+```

package/templates/skills/qa/references/call-site-review.md

@@ -0,0 +1,202 @@
+# Call-Site Review Checklist
+
+## Purpose
+
+When new exported functions are added, QA must review not just the function itself but **where** and **how** it's called. A function can be perfectly implemented but called incorrectly at the call site.
+
+**Origin:** Issue #295 — `rebaseBeforePR()` had thorough unit tests but was called for every issue in a chain loop when the AC specified "only the final branch."
+
+## When to Apply
+
+This review is **triggered** when new exported functions are detected in the diff:
+
+```bash
+# Detect new exported functions (added lines only)
+# Catches: export function foo, export async function foo,
+#          export const foo = () =>, export const foo = async () =>
+git diff main...HEAD | grep -E '^\+export (async )?function \w+' | sed 's/^+//'
+git diff main...HEAD | grep -E '^\+export const \w+ = (async )?\(' | sed 's/^+//'
+```
+
+## Review Steps
+
+### Step 1: Call-Site Inventory
+
+For each new exported function, find where it's called using the Grep tool:
+
+```bash
+# Find call sites for a function (exclude test files)
+Grep(pattern="functionName\\(", glob="*.{ts,tsx}", output_mode="content")
+# Then exclude results from .test. files and __tests__ directories
+```
+
+### Step 2: Condition Audit
+
+For each call site, identify:
+
+1. **What conditions gate the call?**
+   - `if` statements, `&&` guards, ternaries
+   - Mode flags, feature flags, environment checks
+
+2. **Is it in a loop?**
+   - `for`, `while`, `forEach`, `.map()`, `.filter()`, etc.
+   - If yes: Should it run for every iteration or only specific ones?
+
+3. **Is it in an async context?**
+   - Is `await` used appropriately?
+   - Could it cause race conditions?
+
+4. **Error handling at call site?**
+   - Is the call wrapped in try/catch?
+   - What happens if the function throws?
+
+**AC Constraint Matching:**
+
+Compare call-site conditions against AC constraints:
+
+| AC Constraint | Call Site Check |
+|---------------|-----------------|
+| "Only for X" | Is there a guard: `if (X)` before the call? |
+| "When Y happens" | Is the call triggered by the Y event/condition? |
+| "Not in Z mode" | Is there a guard: `if (!Z)` or similar? |
+| "Final item only" | If in loop, is there an index check or break? |
+
+### Step 3: Loop Awareness
+
+When a function is called inside a loop, answer:
+
+1. **Iteration scope:**
+   - Should it run for ALL iterations? → OK
+   - Should it run for FIRST/LAST only? → Check for index guard
+   - Should it run for SOME iterations? → Check for condition filter
+
+2. **Common patterns to verify:**
+
+   ```typescript
+   // LAST only - should have index check
+   for (let i = 0; i < items.length; i++) {
+     if (i === items.length - 1) {
+       newFunction(); // ✅ Guarded for last
+     }
+   }
+
+   // FIRST only - should have index check
+   items.forEach((item, index) => {
+     if (index === 0) {
+       newFunction(); // ✅ Guarded for first
+     }
+   });
+
+   // CONDITIONAL - should have filter
+   for (const item of items) {
+     if (item.shouldProcess) {
+       newFunction(item); // ✅ Conditionally called
+     }
+   }
+   ```
+
+3. **Red flags:**
+   - Function called unconditionally in loop when AC says "only once"
+   - No break/return after the call when AC implies single execution
+   - Missing mode/flag guard when AC specifies conditions
+
+### Step 4: Mode Sensitivity
+
+If the function behaves differently based on mode flags:
+
+1. **Identify mode parameters:**
+   - Does the function accept `options` or `config`?
+   - Are there mode-specific code paths inside?
+
+2. **Verify at call site:**
+   - Is the mode passed correctly?
+   - Does the caller's context match the mode expected?
+
+## Output Format
+
+```markdown
+### Call-Site Review
+
+**New exported functions detected:** N
+
+| Function | Call Sites | Loop? | Conditions | AC Match |
+|----------|-----------|-------|------------|----------|
+| `newFunction()` | `file.ts:123` | No | `if (condition)` | ✅ Matches AC-2 |
+| `anotherFunc()` | `run.ts:456` | Yes (forEach) | None | ⚠️ Missing guard (AC-3 says "final only") |
+| `thirdFunc()` | Not called | - | - | ⚠️ Unused export |
+
+**Findings:**
+- `anotherFunc()` is called in a loop without iteration guard. AC-3 specifies "only for the final item."
+
+**Recommendations:**
+1. Add index check: `if (index === items.length - 1)` before calling `anotherFunc()`
+```
+
+## Verdict Impact
+
+| Finding | Verdict Impact |
+|---------|----------------|
+| All call sites match AC | No impact |
+| Call site missing AC-required guard | `AC_NOT_MET` |
+| Function not called anywhere | `AC_MET_BUT_NOT_A_PLUS` (dead export) |
+| Call site in loop, AC unclear about iteration | `NEEDS_VERIFICATION` |
+
+## Examples
+
+### Example 1: Missing Chain Mode Guard (Issue #295)
+
+**AC:** "Rebase only the final branch in a chain"
+
+**Detection:**
+
+```bash
+Grep(pattern="rebaseBeforePR\\(", glob="*.ts", output_mode="content")
+# Output: src/run.ts:2977:  await rebaseBeforePR(worktreePath)
+```
+
+**Analysis:**
+
+```typescript
+// Found in loop over all chain issues
+for (const result of chainResults) {
+  if (result.success && result.worktreePath) {
+    await rebaseBeforePR(result.worktreePath);  // ⚠️ Called for ALL
+  }
+}
+```
+
+**Finding:** No guard for "final only" — function called for every issue in chain.
+
+**Fix:** Add final-issue check:
+
+```typescript
+for (let i = 0; i < chainResults.length; i++) {
+  const result = chainResults[i];
+  const isFinal = i === chainResults.length - 1;
+  if (result.success && result.worktreePath && isFinal) {
+    await rebaseBeforePR(result.worktreePath);  // ✅ Only final
+  }
+}
+```
+
+### Example 2: Correct Guard Present
+
+**AC:** "Send notification only when status is 'complete'"
+
+**Detection:**
+
+```bash
+Grep(pattern="sendNotification\\(", glob="*.ts", output_mode="content")
+# Output: src/handlers.ts:89:  sendNotification(user.email, message)
+```
+
+**Analysis:**
+
+```typescript
+// Found with proper guard
+if (task.status === 'complete') {
+  sendNotification(user.email, message);  // ✅ Guarded
+}
+```
+
+**Finding:** Call site condition matches AC constraint. No issues.