四級驗證與自動修復：拆解 GSD Verifier 的 Agent 設計與工程實作

// execute-phase.md 中的 verify_phase_goal 步驟
Task(
  prompt="Verify phase {phase_number} goal achievement.
  Phase directory: {phase_dir}
  Phase goal: {goal from ROADMAP.md}
  Check must_haves against actual codebase.
  Create VERIFICATION.md.",
  subagent_type="gsd-verifier",
  model="{verifier_model}"
)

grep "^status:" "$PHASE_DIR"/*-VERIFICATION.md | cut -d: -f2 | tr -d ' '

<role>
You are a GSD phase verifier.
CRITICAL: Do NOT trust SUMMARY.md claims.
SUMMARYs document what Claude SAID it did.
You verify what ACTUALLY exists in the code.
</role>

<verification_process>
  Step 0: 有沒有之前的 VERIFICATION.md？有的話進 RE-VERIFICATION 模式
  Step 1: 載入 Context（PLAN.md、ROADMAP.md）
  Step 2: 建立 must_haves（從 PLAN frontmatter 或 ROADMAP 推導）
  Step 3: 驗證 Observable Truths
  Step 4: 驗證 Artifacts（四級）
  Step 5: 驗證 Key Links（串接）
  Step 6: 需求覆蓋率
  Step 7: Anti-Pattern 掃描
  Step 8: 哪些東西需要人類測
  Step 9: 判定整體 status
  Step 10: 結構化 Gaps 輸出（YAML）
</verification_process>

<stub_detection_patterns>
  // 直接在 Prompt 裡教 AI 認 Stub：
  return <div>Placeholder</div>     // RED FLAG
  onClick={() => {}}                // RED FLAG
  return Response.json([])          // RED FLAG（沒有 DB 查詢的空回傳）
</stub_detection_patterns>

// verify.cjs 中的 cmdVerifyArtifacts 函數（簡化）
function cmdVerifyArtifacts(cwd, planFilePath) {
  // 從 PLAN.md 的 frontmatter 解析 must_haves.artifacts
  const artifacts = parseMustHavesBlock(content, 'artifacts');

  for (const artifact of artifacts) {
    // Level 1: 檔案存在嗎？
    const exists = fs.existsSync(artFullPath);

    if (exists) {
      const lineCount = fileContent.split('\n').length;

      // Level 2: 行數夠嗎？（防 Stub）
      if (artifact.min_lines && lineCount < artifact.min_lines) {
        check.issues.push(
          `Only ${lineCount} lines, need ${artifact.min_lines}`,
        );
      }
      // Level 2: 有沒有包含指定的程式碼模式？
      if (artifact.contains && !fileContent.includes(artifact.contains)) {
        check.issues.push(`Missing pattern: ${artifact.contains}`);
      }
      // Level 2: 有沒有導出指定的函式？
      if (artifact.exports) {
        for (const exp of exports) {
          if (!fileContent.includes(exp))
            check.issues.push(`Missing export: ${exp}`);
        }
      }
    }
  }
  // 回傳 JSON：{ all_passed, passed, total, artifacts: [...] }
}

# Prompt 裡教 Verifier 怎麼檢查「有沒有被 Import 且被使用」
# Import check
grep -r "import.*$artifact_name" src/ --include="*.ts" --include="*.tsx" | wc -l

# Usage check (beyond imports)
grep -r "$artifact_name" src/ --include="*.ts" --include="*.tsx" | grep -v "import" | wc -l

# Prompt 教 Verifier 追溯資料流：
# 1. 找到 state 變數
grep -n -E "useState|useQuery|useSWR" "$artifact"

# 2. 找到資料來源
grep -n -A 5 "set${STATE_VAR}" "$artifact" | grep -E "fetch|axios|query"

# 3. 驗證來源是否有真實查詢
grep -n -E "prisma\.|db\.|findMany|select|FROM" "$source_file"

# 4. 抓空包彈：回傳寫死空陣列
grep -n -E "return.*json\(\s*\[\]|return.*json\(\s*\{\}" "$source_file"

# PLAN.md frontmatter 範例
must_haves:
  truths:
    - 'User can see existing messages'
    - 'User can send a message'
  artifacts:
    - path: 'src/components/Chat.tsx'
      provides: 'Message list rendering'
      min_lines: 50
      contains: 'useEffect'
      exports: ['ChatComponent']
  key_links:
    - from: 'Chat.tsx'
      to: 'api/chat'
      via: 'fetch in useEffect'
      pattern: 'fetch.*api/chat'

# VERIFICATION.md 的 frontmatter
status: gaps_found
score: 3/5 must-haves verified
gaps:
  - truth: 'User can send a message'
    status: failed
    reason: 'Chat.tsx onSubmit handler only calls e.preventDefault()'
    artifacts:
      - path: 'src/components/Chat.tsx'
        issue: 'Form handler is stub - no API call'
    missing:
      - 'fetch POST to /api/chat in onSubmit handler'

#!/bin/bash
# 最小化 Verifier 腳本
for file in $EXPECTED_FILES; do
  if [ ! -f "$file" ]; then
    echo "MISSING: $file"
  elif [ $(wc -l < "$file") -lt 20 ]; then
    echo "STUB: $file ($(wc -l < "$file") lines)"
  else
    echo "OK: $file"
  fi
done

對於每個通過 Level 1-2 的檔案：
1. 跑 grep -r "import.*{file_name}" src/ | wc -l → 沒人 import 就是 ORPHANED
2. 跑 grep -r "{file_name}" src/ | grep -v "import" | wc -l → import 了但沒用也是問題
3. 如果是渲染元件，追溯 useState 的資料來源，確認不是寫死的假資料