@walwal-harness/cli 2.4.0 → 3.2.0

package/assets/templates/evaluation-functional.md.template

@@ -0,0 +1,119 @@
+# Evaluation — Functional (Sprint {{SPRINT}})
+
+> Generated by: evaluator-functional
+> Date: {{DATE}}
+> Verdict: **PENDING**
+
+## 1. Scoring Rubric
+
+> **Threshold: 2.80 / 3.00 = PASS**
+> Score 2.79 이하는 이유를 불문하고 FAIL.
+> 모든 항목에 Evidence(근거)를 반드시 기입. Evidence 없는 Score는 0점 처리.
+
+| # | Criterion | Weight | Score (0-3) | Evidence |
+|---|-----------|--------|-------------|----------|
+| R1 | API Contract 준수 — 모든 엔드포인트가 api-contract.json과 일치 (method, path, request/response schema, status codes) | 25% | | |
+| R2 | Acceptance Criteria 통과 — feature-list.json의 모든 AC 항목 실행 결과 | 25% | | |
+| R3 | 부정 테스트 (Negative Testing) — 각 엔드포인트별 최소 2개 비정상 시나리오 (빈 입력, 잘못된 타입, 미인증, 권한 없음, 중복, 초과값) | 20% | | |
+| R4 | E2E 시나리오 통과 — Playwright로 사용자 플로우 전체 재현 (회원가입→로그인→핵심기능→로그아웃 등) | 15% | | |
+| R5 | 에러 핸들링 & 엣지케이스 — 서버 에러 응답 형식 일관성, DB 제약조건 위반 처리, 동시성 충돌 | 15% | | |
+
+### Scoring Guide (엄격 적용)
+
+| Score | 의미 | 기준 |
+|-------|------|------|
+| 3 | 완벽 | 모든 케이스 통과, 추가 검증 불필요, 엣지케이스까지 커버 |
+| 2 | 충족 | 핵심 기능 동작하나 경미한 이슈 1-2건 존재 (로그 누락, 응답 필드 오타 등) |
+| 1 | 부분 충족 | 핵심 기능은 동작하나 명확한 수정 필요 (잘못된 status code, 누락된 validation 등) |
+| 0 | 미충족 | 미구현, 서버 에러, 또는 contract 불일치 |
+
+### Anti-Rubber-Stamping Check
+
+Score를 기입하기 전에 반드시 아래 질문에 답하라:
+- [ ] "이 엔드포인트에 실제로 요청을 보내고 응답을 확인했는가?" (추측 = 0점)
+- [ ] "정상 케이스뿐 아니라 비정상 케이스도 테스트했는가?" (정상만 = Score 최대 2)
+- [ ] "api-contract.json과 실제 응답을 문자열 수준으로 비교했는가?"
+
+## 2. Acceptance Criteria Checklist
+
+> feature-list.json의 acceptance_criteria를 기계적으로 실행한 결과.
+> 각 AC에 대해 PASS/FAIL + 실제 결과를 기록.
+
+| Feature | AC ID | Description | Type | Expected | Actual | Result |
+|---------|-------|-------------|------|----------|--------|--------|
+| | | | | | | |
+
+**AC Summary**: 0/0 passed (0%)
+**AC 전체 통과가 아니면 R2는 최대 Score 1**
+
+## 3. Negative Test Results
+
+> 각 엔드포인트별 최소 2개 부정 테스트. 미실시 엔드포인트가 있으면 R3 = 0.
+
+| Endpoint | Test Case | Expected | Actual | Result |
+|----------|-----------|----------|--------|--------|
+| | | | | |
+
+## 4. E2E Scenario Log
+
+> Playwright 실행 로그. 스크린샷 경로 포함.
+
+```
+(Playwright 실행 결과를 여기에 붙여넣기)
+```
+
+## 5. Regression Check
+
+> 이전 Sprint에서 PASS된 기능 재검증 결과.
+> Sprint 1이면 "N/A - 첫 스프린트"로 기입.
+
+| Sprint | Feature | AC ID | Result | Notes |
+|--------|---------|-------|--------|-------|
+| | | | | |
+
+**Regression Summary**: 0/0 passed
+**회귀 실패가 1건이라도 있으면 전체 Verdict = FAIL (신규 기능 점수 무관)**
+
+## 6. Cross-Validation Data
+
+> evaluator-visual이 참조할 수 있도록 기계 판독 가능한 결과 요약.
+> 이 섹션은 반드시 아래 JSON 코드블록 형식을 유지할 것.
+
+```json
+{
+  "evaluator": "functional",
+  "sprint": {{SPRINT}},
+  "verdict": "PENDING",
+  "total_score": 0.00,
+  "threshold": 2.80,
+  "criteria_scores": {
+    "R1_api_contract": 0,
+    "R2_acceptance_criteria": 0,
+    "R3_negative_testing": 0,
+    "R4_e2e_scenario": 0,
+    "R5_error_handling": 0
+  },
+  "ac_pass_rate": 0.0,
+  "negative_test_count": 0,
+  "regression_failures": 0,
+  "endpoints_tested": [],
+  "pages_tested": []
+}
+```
+
+## 7. Final Verdict
+
+| Metric | Value |
+|--------|-------|
+| Weighted Score | 0.00 / 3.00 |
+| Threshold | 2.80 |
+| AC Pass Rate | 0% |
+| Regression Failures | 0 |
+| **Verdict** | **PENDING** |
+
+### Verdict Rules (위반 불가)
+1. Weighted Score < 2.80 → **FAIL**
+2. AC Pass Rate < 100% → **FAIL** (부분 통과 불인정)
+3. Regression Failures > 0 → **FAIL** (신규 점수 무관)
+4. Evidence 누락 항목 존재 → 해당 항목 Score = 0으로 재계산
+5. 부정 테스트 미실시 엔드포인트 존재 → R3 = 0으로 재계산

package/assets/templates/evaluation-visual.md.template

@@ -0,0 +1,151 @@
+# Evaluation — Visual (Sprint {{SPRINT}})
+
+> Generated by: evaluator-visual
+> Date: {{DATE}}
+> Verdict: **PENDING**
+
+## 1. Scoring Rubric
+
+> **Threshold: 2.80 / 3.00 = PASS**
+> Score 2.79 이하는 이유를 불문하고 FAIL.
+> 모든 항목에 Evidence(스크린샷 경로 또는 DOM 스냅샷)를 반드시 기입. Evidence 없는 Score는 0점 처리.
+
+| # | Criterion | Weight | Score (0-3) | Evidence |
+|---|-----------|--------|-------------|----------|
+| V1 | 레이아웃 정확성 — 모든 페이지가 디자인 의도대로 배치, 겹침/넘침/잘림 없음 | 20% | | |
+| V2 | 반응형 적합성 — 최소 3개 뷰포트(mobile 375px, tablet 768px, desktop 1280px)에서 정상 렌더링 | 20% | | |
+| V3 | 접근성 (a11y) — WCAG 2.1 AA 준수, axe-core 위반 0건, 키보드 네비게이션 가능, ARIA 라벨 존재 | 20% | | |
+| V4 | 시각적 일관성 — 색상/타이포/간격이 디자인 시스템과 일치, AI슬롭 패턴(그라데이션 남용, 무의미한 아이콘, 과도한 그림자) 없음 | 20% | | |
+| V5 | 인터랙션 피드백 — 로딩 상태, 에러 상태, 빈 상태, 호버/포커스 상태 모두 구현됨 | 20% | | |
+
+### Scoring Guide (엄격 적용)
+
+| Score | 의미 | 기준 |
+|-------|------|------|
+| 3 | 완벽 | 모든 뷰포트, 모든 상태에서 결함 없음. 프로덕션 출시 가능 수준 |
+| 2 | 충족 | 핵심 화면 정상이나 경미한 시각 이슈 1-2건 (1px 오차, 미사용 상태 아이콘 누락 등) |
+| 1 | 부분 충족 | 특정 뷰포트에서 레이아웃 깨짐, 또는 접근성 위반 3건 이상 |
+| 0 | 미충족 | 렌더링 실패, 빈 화면, 또는 핵심 UI 요소 누락 |
+
+### Anti-Rubber-Stamping Check
+
+Score를 기입하기 전에 반드시 아래 질문에 답하라:
+- [ ] "이 페이지를 실제로 3개 뷰포트에서 스크린샷을 찍어 확인했는가?" (추측 = 0점)
+- [ ] "axe-core 또는 접근성 검사를 실제로 실행했는가?" (미실행 = V3 최대 1점)
+- [ ] "이전 Sprint 스크린샷과 비교하여 의도치 않은 시각 변경이 없는지 확인했는가?"
+- [ ] "내가 이 UI를 직접 만들었다면, 이 수준으로 디자인 리뷰를 통과시키겠는가?" (NO = FAIL)
+
+## 2. Screenshot Matrix
+
+> 모든 페이지 x 3개 뷰포트의 스크린샷. 누락 셀이 있으면 해당 페이지 Score 산정 불가.
+
+| Page | Mobile (375px) | Tablet (768px) | Desktop (1280px) | Issues |
+|------|---------------|----------------|-------------------|--------|
+| | | | | |
+
+**Screenshot Coverage**: 0/0 pages x 3 viewports = 0/0
+
+## 3. Accessibility Audit
+
+> axe-core 또는 Playwright accessibility snapshot 결과.
+
+| Page | Violations | Critical | Serious | Moderate | Minor |
+|------|-----------|----------|---------|----------|-------|
+| | | | | | |
+
+**a11y Summary**: 0 total violations across 0 pages
+**Critical 또는 Serious 위반이 1건이라도 있으면 V3 = 0**
+
+## 4. Interaction States Checklist
+
+> 각 핵심 컴포넌트의 상태별 구현 확인.
+
+| Component | Default | Loading | Error | Empty | Hover | Focus | Disabled |
+|-----------|---------|---------|-------|-------|-------|-------|----------|
+| | | | | | | | |
+
+**상태 커버리지**: 0/0 components x states
+
+## 5. AI Slop Detection
+
+> AI 생성 UI의 흔한 저품질 패턴 감지.
+
+| Pattern | Detected? | Location | Severity |
+|---------|-----------|----------|----------|
+| 무의미한 그라데이션 | | | |
+| 과도한 그림자/블러 | | | |
+| 장식용 아이콘 남발 | | | |
+| 불필요한 애니메이션 | | | |
+| 일관성 없는 간격/정렬 | | | |
+| placeholder 텍스트 미교체 | | | |
+| 깨진 이미지/아이콘 | | | |
+
+**AI Slop이 2건 이상 감지되면 V4 = 최대 1점**
+
+## 6. Regression Visual Diff
+
+> 이전 Sprint 스크린샷과 현재 비교. 의도치 않은 시각 변경 감지.
+> Sprint 1이면 "N/A - 첫 스프린트"로 기입.
+
+| Page | Viewport | Change Detected | Intentional? | Notes |
+|------|----------|----------------|-------------|-------|
+| | | | | |
+
+**의도치 않은 시각 변경이 1건이라도 있으면 Verdict = FAIL**
+
+## 7. Cross-Validation with Functional
+
+> evaluation-functional.md의 Cross-Validation Data와 교차 검증.
+
+| Check | Functional Result | Visual Result | Consistent? |
+|-------|------------------|---------------|-------------|
+| 페이지 존재 여부 | endpoints_tested → pages | 실제 렌더링 확인 | |
+| 폼 제출 결과 | API 응답 status | UI 피드백 메시지 | |
+| 에러 표시 | 에러 응답 코드 | 에러 UI 렌더링 | |
+
+**불일치가 1건이라도 있으면 관련 Feature의 해당 항목 재검증 필요 → CONDITIONAL FAIL**
+
+```json
+{
+  "evaluator": "visual",
+  "sprint": {{SPRINT}},
+  "verdict": "PENDING",
+  "total_score": 0.00,
+  "threshold": 2.80,
+  "criteria_scores": {
+    "V1_layout": 0,
+    "V2_responsive": 0,
+    "V3_accessibility": 0,
+    "V4_consistency": 0,
+    "V5_interaction_states": 0
+  },
+  "screenshot_coverage": 0.0,
+  "a11y_violations": { "critical": 0, "serious": 0, "moderate": 0, "minor": 0 },
+  "ai_slop_count": 0,
+  "regression_visual_changes": 0,
+  "cross_validation_inconsistencies": 0,
+  "pages_tested": []
+}
+```
+
+## 8. Final Verdict
+
+| Metric | Value |
+|--------|-------|
+| Weighted Score | 0.00 / 3.00 |
+| Threshold | 2.80 |
+| Screenshot Coverage | 0% |
+| a11y Critical+Serious | 0 |
+| AI Slop Count | 0 |
+| Regression Visual Changes | 0 |
+| Cross-Validation Inconsistencies | 0 |
+| **Verdict** | **PENDING** |
+
+### Verdict Rules (위반 불가)
+1. Weighted Score < 2.80 → **FAIL**
+2. Screenshot 누락 페이지 존재 → 해당 페이지 관련 항목 Score = 0으로 재계산
+3. a11y Critical 또는 Serious > 0 → V3 = 0으로 재계산
+4. AI Slop >= 2 → V4 = 최대 1점으로 재계산
+5. Regression 의도치 않은 변경 > 0 → **FAIL** (점수 무관)
+6. Cross-Validation 불일치 > 0 → **CONDITIONAL FAIL** (해당 Feature 재검증)
+7. Evidence 누락 항목 존재 → 해당 항목 Score = 0으로 재계산

package/assets/templates/memory.md

@@ -3,4 +3,24 @@
 > Dispatcher가 관리. **모든 에이전트**는 세션 시작 시 이 파일을 읽고 학습된 규칙을 따릅니다.
 > gotchas(에이전트별 실수 기록)와 달리, 이 파일은 **프로젝트 전체에 적용되는 구조적 교훈**을 담습니다.
 
+## 항목 형식
+
+```markdown
+### [M-NNN] 간결한 제목
+- **Date**: YYYY-MM-DD
+- **Status**: unverified | verified
+- **TTL**: YYYY-MM-DD (기본 +60일. 만료 후 Planner가 리뷰)
+- **Lesson**: 교훈 내용
+- **Context**: 발견 배경
+- **Applies to**: 적용 대상 에이전트/상황
+```
+
+## 오염 방어 규칙
+
+- 새 항목은 반드시 `unverified` 상태로 시작
+- Planner가 스프린트 리뷰 시 유효성 확인 후 `verified` 승격
+- TTL 만료 항목은 Planner가 리뷰: 갱신 또는 삭제
+- 환각(hallucination) 의심 항목: 코드/git 이력으로 검증 불가하면 즉시 삭제
+- 항목이 15개 초과 시 가장 오래된 unverified 항목부터 정리
+
 <!-- 항목이 추가되면 아래에 기록됩니다 -->

package/assets/templates/progress.json.template

@@ -17,6 +17,12 @@
     "message": null,
     "retry_target": null
   },
+  "artifacts": {
+    "plan.md": { "status": "pending", "updated_by": null, "updated_at": null },
+    "feature-list.json": { "status": "pending", "updated_by": null, "updated_at": null },
+    "api-contract.json": { "status": "pending", "updated_by": null, "updated_at": null },
+    "sprint-contract.md": { "status": "pending", "updated_by": null, "updated_at": null }
+  },
   "updated_at": "{{DATE}}",
   "history": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@walwal-harness/cli",
-  "version": "2.4.0",
+  "version": "3.2.0",
   "description": "Production harness for AI agent engineering — Planner, Generator(BE/FE), Evaluator(Func/Visual), optional Brainstormer (requirements refinement). Supports React and Flutter FE stacks.",
   "bin": {
     "walwal-harness": "bin/init.js"
@@ -34,5 +34,8 @@
     "scripts/",
     "assets/",
     "gotchas/"
-  ]
+  ],
+  "dependencies": {
+    "@walwal-harness/cli": "^3.2.0"
+  }
 }

package/scripts/harness-next.sh

@@ -6,6 +6,7 @@ set -e
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 source "$SCRIPT_DIR/lib/harness-render-progress.sh"
+source "$SCRIPT_DIR/lib/harness-guardrail.sh"
 
 # ─────────────────────────────────────────
 # Resolve project root
@@ -41,17 +42,24 @@ next_agent=$(jq -r '.next_agent // "null"' "$PROGRESS")
 retry_count=$(jq -r '.sprint.retry_count // 0' "$PROGRESS")
 max_retries=$(jq -r '.flow.max_retries_per_sprint // 10' "$CONFIG" 2>/dev/null || echo 10)
 
-# fe_stack 치환 (Flutter 지원) — pipeline.json 에서 읽음
+# fe_stack + fe_target 치환 (Flutter Web/Mobile/Desktop 지원) — pipeline.json 에서 읽음
 fe_stack="react"
+fe_target="web"
 if [ -f "$PIPELINE_JSON" ]; then
   fe_stack=$(jq -r '.fe_stack // "react"' "$PIPELINE_JSON" 2>/dev/null || echo "react")
+  fe_target=$(jq -r '.fe_target // empty' "$PIPELINE_JSON" 2>/dev/null || true)
+  if [ -z "$fe_target" ]; then
+    # pipeline.json 에 fe_target 미지정 시 config.json 의 _default_target 사용
+    fe_target=$(jq -r ".flow.pipeline_selection.fe_stack_substitution.${fe_stack}._default_target // \"web\"" "$CONFIG" 2>/dev/null || echo "web")
+  fi
 fi
 
 # ─────────────────────────────────────────
-# fe_stack 치환 헬퍼
-#   pipeline_selection.pipelines에서 읽은 에이전트명을 fe_stack에 따라 치환
+# fe_stack + fe_target 치환 헬퍼
+#   pipeline_selection.pipelines 에서 읽은 에이전트명을 fe_stack/fe_target 에 따라 치환
 #   - react: 그대로
-#   - flutter: generator-frontend → generator-frontend-flutter 등, __skip__ 은 건너뜀
+#   - flutter+web: generator-frontend → generator-frontend-flutter 만 치환, eval 은 그대로 (Playwright 사용 가능)
+#   - flutter+mobile/desktop: eval 도 정적 분석용으로 치환, evaluator-visual 은 __skip__
 # ─────────────────────────────────────────
 substitute_fe_stack() {
   local agent="$1"
@@ -60,10 +68,94 @@ substitute_fe_stack() {
     return
   fi
   local sub
-  sub=$(jq -r ".flow.pipeline_selection.fe_stack_substitution.flutter[\"${agent}\"] // \"${agent}\"" "$CONFIG" 2>/dev/null)
+  sub=$(jq -r ".flow.pipeline_selection.fe_stack_substitution.${fe_stack}.by_target[\"${fe_target}\"][\"${agent}\"] // \"${agent}\"" "$CONFIG" 2>/dev/null)
   echo "$sub"
 }
 
+# ─────────────────────────────────────────
+# Pre-Eval Gate — deterministic checks before Evaluator
+#   Generator가 완료되고 다음이 Evaluator일 때, lint/type/test를 먼저 실행.
+#   실패 시 Evaluator를 건너뛰고 Generator로 리라우팅.
+# ─────────────────────────────────────────
+run_pre_eval_gate() {
+  local next="$1"
+  local gate_enabled
+  gate_enabled=$(jq -r '.flow.pre_eval_gate.enabled // false' "$CONFIG" 2>/dev/null)
+  if [ "$gate_enabled" != "true" ]; then return 0; fi
+
+  # Evaluator 에이전트인지 확인
+  case "$next" in
+    evaluator-*) ;;
+    *) return 0 ;;
+  esac
+
+  local timeout
+  timeout=$(jq -r '.flow.pre_eval_gate.timeout_seconds // 120' "$CONFIG" 2>/dev/null)
+
+  # 실패 위치 결정 (backend or frontend)
+  local location="backend"
+  local checks_key="backend_checks"
+  if [ "$current_agent" = "generator-frontend" ] || [ "$current_agent" = "generator-frontend-flutter" ]; then
+    location="frontend"
+    checks_key="frontend_checks"
+  fi
+
+  local -a checks
+  mapfile -t checks < <(jq -r ".flow.pre_eval_gate.${checks_key}[]" "$CONFIG" 2>/dev/null)
+
+  if [ ${#checks[@]} -eq 0 ]; then return 0; fi
+
+  echo ""
+  echo "  ── Pre-Eval Gate ──────────────────────"
+  local all_pass=true
+  local fail_log=""
+
+  for cmd in "${checks[@]}"; do
+    printf "  %-40s " "$cmd"
+    local output
+    if output=$(cd "$PROJECT_ROOT" && timeout "${timeout}s" bash -c "$cmd" 2>&1); then
+      echo "✓"
+    else
+      echo "✗"
+      all_pass=false
+      fail_log+="[FAIL] $cmd"$'\n'"$output"$'\n\n'
+    fi
+  done
+
+  if [ "$all_pass" = true ]; then
+    echo "  Gate: PASS — proceeding to $next"
+    echo ""
+    return 0
+  else
+    echo ""
+    echo "  Gate: FAIL — rerouting to $current_agent"
+    echo ""
+
+    # progress.json 업데이트: 실패 기록 + Generator로 리라우팅
+    local new_retry=$((retry_count + 1))
+    local fail_summary
+    fail_summary=$(echo "$fail_log" | head -20)
+
+    jq --arg agent "$current_agent" \
+       --arg loc "$location" \
+       --arg msg "Pre-eval gate failed: $fail_summary" \
+       --arg target "$current_agent" \
+       --argjson retry "$new_retry" \
+       '.sprint.status = "failed" |
+        .sprint.retry_count = $retry |
+        .agent_status = "failed" |
+        .next_agent = $target |
+        .failure.agent = $agent |
+        .failure.location = $loc |
+        .failure.message = $msg |
+        .failure.retry_target = $target' "$PROGRESS" > "${PROGRESS}.tmp" && mv "${PROGRESS}.tmp" "$PROGRESS"
+
+    # next_agent를 Generator로 덮어쓰기
+    next_agent="$current_agent"
+    return 1
+  fi
+}
+
 # ─────────────────────────────────────────
 # Determine next agent
 # ─────────────────────────────────────────
@@ -131,6 +223,71 @@ if [ "$agent_status" = "completed" ] && [ "$next_agent" = "null" ]; then
   next_agent=$(compute_next_agent "$current_agent" "$agent_status")
 fi
 
+# ─────────────────────────────────────────
+# Artifact Prerequisites — 선행 아티팩트 상태 검증
+# ─────────────────────────────────────────
+verify_artifact_prerequisites() {
+  local target_agent="$1"
+  local states_order='["pending","draft","reviewed","approved"]'
+
+  # 에이전트의 prerequisites 가져오기
+  local prereqs
+  prereqs=$(jq -r ".artifacts.prerequisites[\"${target_agent}\"] // empty" "$CONFIG" 2>/dev/null)
+  if [ -z "$prereqs" ] || [ "$prereqs" = "null" ]; then return 0; fi
+
+  local all_met=true
+  echo ""
+  echo "  ── Artifact Prerequisites ─────────────"
+
+  # prereqs의 각 키(artifact명)를 순회
+  while IFS='=' read -r artifact required_status; do
+    artifact=$(echo "$artifact" | tr -d '"' | tr -d ' ')
+    required_status=$(echo "$required_status" | tr -d '"' | tr -d ' ')
+    if [ -z "$artifact" ]; then continue; fi
+
+    local current_status
+    current_status=$(jq -r ".artifacts[\"${artifact}\"].status // \"pending\"" "$PROGRESS" 2>/dev/null)
+
+    # 상태 순서 비교
+    local required_idx current_idx
+    required_idx=$(echo "$states_order" | jq "index(\"$required_status\") // 0")
+    current_idx=$(echo "$states_order" | jq "index(\"$current_status\") // 0")
+
+    if [ "$current_idx" -ge "$required_idx" ]; then
+      printf "  ✓ %-25s %s (required: %s)\n" "$artifact" "$current_status" "$required_status"
+    else
+      printf "  ✗ %-25s %s (required: %s)\n" "$artifact" "$current_status" "$required_status"
+      all_met=false
+    fi
+  done < <(jq -r ".artifacts.prerequisites[\"${target_agent}\"] | to_entries[] | \"\(.key)=\(.value)\"" "$CONFIG" 2>/dev/null)
+
+  echo ""
+
+  if [ "$all_met" = true ]; then
+    echo "  Prerequisites: PASS"
+  else
+    echo "  Prerequisites: FAIL — preceding agent must complete artifacts first"
+  fi
+  echo ""
+
+  [ "$all_met" = true ] && return 0 || return 1
+}
+
+# ─────────────────────────────────────────
+# Runtime Guardrail — 파일 소유권 검증
+# ─────────────────────────────────────────
+if [ "$agent_status" = "completed" ]; then
+  verify_file_ownership "$PROJECT_ROOT" || true
+fi
+
+# ─────────────────────────────────────────
+# Run Pre-Eval Gate (if applicable)
+# ─────────────────────────────────────────
+if [ "$agent_status" = "completed" ]; then
+  run_pre_eval_gate "$next_agent" || true
+  verify_artifact_prerequisites "$next_agent" || true
+fi
+
 # ─────────────────────────────────────────
 # Render progress
 # ─────────────────────────────────────────
@@ -142,6 +299,18 @@ echo ""
 # Generate next-prompt.txt
 # ─────────────────────────────────────────
 if [ "$next_agent" != "null" ] && [ "$next_agent" != "archive" ] && [ "$agent_status" != "blocked" ]; then
+  # ── Escalation check: 3회 실패 시 Planner에게 scope 축소 요청 ──
+  escalate_after=$(jq -r '.flow.escalate_to_planner_after // 3' "$CONFIG" 2>/dev/null || echo 3)
+  if [ "$retry_count" -ge "$escalate_after" ] && [ "$sprint_status" = "failed" ] && [ "$next_agent" != "planner" ]; then
+    echo "  ⚠ Escalation: ${retry_count}회 실패 — Planner에게 scope 축소/접근 변경 요청"
+    next_agent="planner"
+    # progress.json에 에스컬레이션 기록
+    jq --arg msg "Escalated after ${retry_count} failures. Planner must review scope or approach." \
+       '.next_agent = "planner" |
+        .failure.message = $msg |
+        .failure.retry_target = "planner"' "$PROGRESS" > "${PROGRESS}.tmp" && mv "${PROGRESS}.tmp" "$PROGRESS"
+  fi
+
   # Build prompt
   prompt="/harness-${next_agent} 를 실행하세요."
 
@@ -155,14 +324,105 @@ if [ "$next_agent" != "null" ] && [ "$next_agent" != "archive" ] && [ "$agent_st
 
   prompt+=$'\n'".harness/progress.json을 읽고 현재 상태를 확인하세요."
 
-  # Add failure context if retrying
+  # Add failure context if retrying (include previous failure summary)
   failure_msg=$(jq -r '.failure.message // empty' "$PROGRESS")
   if [ -n "$failure_msg" ] && [ "$failure_msg" != "null" ]; then
     prompt+=$'\n\n'"이전 실패 사유: ${failure_msg}"
+    prompt+=$'\n'"같은 접근을 반복하지 말고, 실패 원인을 분석한 후 다른 전략으로 시도하세요."
   fi
 
   echo "$prompt" > "$NEXT_PROMPT"
 
+  # ── Generate structured handoff.json ──
+  HANDOFF="$PROJECT_ROOT/.harness/handoff.json"
+  FEATURE_LIST="$PROJECT_ROOT/.harness/actions/feature-list.json"
+
+  # Collect available artifacts
+  local -a artifacts_ready=()
+  for f in plan.md feature-list.json api-contract.json sprint-contract.md evaluation-functional.md evaluation-visual.md; do
+    if [ -f "$PROJECT_ROOT/.harness/actions/$f" ]; then
+      artifacts_ready+=("$f")
+    fi
+  done
+  local artifacts_json
+  artifacts_json=$(printf '%s\n' "${artifacts_ready[@]}" | jq -R . | jq -s .)
+
+  # Collect focus features (incomplete ones)
+  local focus_features="[]"
+  if [ -f "$FEATURE_LIST" ]; then
+    focus_features=$(jq '[.features[]? | select(.passes == null or (.passes | length) == 0 or ((.passes // []) | map(select(. == "evaluator-functional")) | length == 0)) | .id] | .[0:5]' "$FEATURE_LIST" 2>/dev/null || echo "[]")
+  fi
+
+  # ── Regression data: collect previous sprint's passed AC from archive ──
+  local regression_source="null"
+  local prev_sprint=$((sprint_num - 1))
+  local prev_archive="$PROJECT_ROOT/.harness/archive/sprint-$(printf '%03d' $prev_sprint)"
+  if [ "$prev_sprint" -ge 1 ] && [ -d "$prev_archive" ]; then
+    if [ -f "$prev_archive/feature-list.json" ]; then
+      regression_source=$(jq '{
+        sprint: '"$prev_sprint"',
+        passed_features: [.features[]? | select((.passes // []) | map(select(. == "evaluator-functional")) | length > 0) | {id, name, acceptance_criteria}],
+        archive_path: "'"$prev_archive"'"
+      }' "$prev_archive/feature-list.json" 2>/dev/null || echo "null")
+    fi
+  fi
+
+  # ── Eval-specific scoring config ──
+  local eval_config="null"
+  local cross_validation_data="null"
+  case "$next_agent" in
+    evaluator-*)
+      eval_config=$(jq '{
+        pass_threshold: .evaluation.scoring.pass_threshold,
+        scale: .evaluation.scoring.scale,
+        verdict_rules: .evaluation.scoring.verdict_rules,
+        regression_enabled: .evaluation.regression.enabled,
+        cross_validation_enabled: .evaluation.cross_validation.enabled,
+        adversarial_rules: .agents["'"$next_agent"'"].adversarial_rules.rules,
+        forbidden: .agents["'"$next_agent"'"].adversarial_rules.forbidden
+      }' "$CONFIG" 2>/dev/null || echo "null")
+      ;;
+  esac
+
+  # ── Cross-Validation: evaluator-visual이면 functional 결과 파싱 ──
+  if [ "$next_agent" = "evaluator-visual" ]; then
+    local func_eval="$PROJECT_ROOT/.harness/actions/evaluation-functional.md"
+    if [ -f "$func_eval" ]; then
+      # evaluation-functional.md 내 JSON 코드블록에서 Cross-Validation Data 추출
+      cross_validation_data=$(sed -n '/```json/,/```/p' "$func_eval" | tail -n +2 | head -n -1 | jq 'select(.evaluator == "functional")' 2>/dev/null || echo "null")
+    fi
+  fi
+
+  # Build handoff.json
+  jq -n \
+    --arg from "${current_agent:-dispatcher}" \
+    --arg to "$next_agent" \
+    --argjson sprint "$sprint_num" \
+    --argjson retry "$retry_count" \
+    --arg status "$sprint_status" \
+    --arg failure_msg "${failure_msg:-}" \
+    --argjson artifacts "$artifacts_json" \
+    --argjson focus "$focus_features" \
+    --argjson regression "$regression_source" \
+    --argjson eval_config "$eval_config" \
+    --argjson cross_val "$cross_validation_data" \
+    --arg timestamp "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+    '{
+      from: $from,
+      to: $to,
+      sprint: $sprint,
+      retry_count: $retry,
+      sprint_status: $status,
+      failure_context: (if $failure_msg != "" then $failure_msg else null end),
+      artifacts_ready: $artifacts,
+      focus_features: $focus,
+      regression: $regression,
+      eval_config: $eval_config,
+      cross_validation_from_functional: $cross_val,
+      warnings: [],
+      timestamp: $timestamp
+    }' > "$HANDOFF"
+
 elif [ "$next_agent" = "archive" ]; then
   cat > "$NEXT_PROMPT" <<'PROMPT'
 Sprint 문서를 아카이브 하세요.