@walwal-harness/cli 2.4.0 → 3.2.0

package/README.md

@@ -155,17 +155,18 @@ Brainstormer? → Planner → Generator-BE → Evaluator-Func(API-only)
 
 > `Brainstormer?` = Dispatcher가 사용자에게 확인 후 조건부 실행. 명확한 PRD/OpenAPI가 있으면 생략 가능.
 
-### Flutter 프로젝트 자동 감지
+### Flutter 프로젝트 자동 감지 (Web / Mobile / Desktop)
 
-`pubspec.yaml` + `flutter:` 키가 감지되면 FE 에이전트가 **자동 치환**됩니다:
+`pubspec.yaml` + `flutter:` 키가 감지되면 FE 에이전트가 **자동 치환**됩니다. **Flutter Web** 은 컴파일 결과가 HTML+JS+CSS 이므로 React 와 동일하게 Playwright 기반 evaluator 를 그대로 사용하고, **Mobile/Desktop** 만 정적 분석 evaluator 로 교체됩니다.
 
-| React (기본) | Flutter |
-|-------------|---------|
-| `generator-frontend` | `generator-frontend-flutter` |
-| `evaluator-functional` (Playwright) | `evaluator-functional-flutter` (flutter analyze/test) |
-| `evaluator-visual` | **SKIP** (브라우저 없음) |
+| fe_stack | fe_target | Generator | Eval-Functional | Eval-Visual |
+|----------|-----------|-----------|----------------|-------------|
+| react | (n/a) | `generator-frontend` | `evaluator-functional` (Playwright) | `evaluator-visual` |
+| **flutter** | **web** | `generator-frontend-flutter` | **`evaluator-functional`** (Playwright!) | **`evaluator-visual`** (Playwright!) |
+| **flutter** | mobile | `generator-frontend-flutter` | `evaluator-functional-flutter` (flutter analyze/test) | **SKIP** |
+| **flutter** | desktop | `generator-frontend-flutter` | `evaluator-functional-flutter` (flutter analyze/test) | **SKIP** |
 
-치환은 `pipeline.json.fe_stack` 값에 의해 `harness-next.sh`가 자동 처리합니다. Planner가 프로젝트 스캔 결과를 보고 `fe_stack`을 확정합니다.
+**감지 방식**: `scan-project.sh` 가 Flutter 프로젝트의 `web/index.html`, `android/`, `ios/`, `macos/`, `windows/`, `linux/` 디렉터리 존재 여부로 `fe_target` 을 자동 판정. 멀티 타겟 또는 모호한 경우 Planner 가 사용자에게 확인합니다. 치환은 `pipeline.json.fe_stack + fe_target` 조합에 의해 `harness-next.sh` 가 자동 처리합니다.
 
 ---
 
@@ -269,20 +270,24 @@ Evaluator는 기능 테스트 전에 AGENTS.md의 IA-MAP과 실제 폴더 구조
 | Evaluator-Visual | `harness-evaluator-visual` — 스크린샷 기반 디자인/접근성/반응형 검증 |
 | 레퍼런스 | Vercel Best Practices, Design System Rules, AI Forbidden Patterns, Component Patterns |
 
-### Flutter (Dart)
+### Flutter (Dart) — Web / Mobile / Desktop
 
-| 항목 | 상세 |
-|------|------|
-| Generator | `harness-generator-frontend-flutter` — Riverpod + integrated_data_layer(Retrofit) + ARB i18n |
-| Evaluator-Func | `harness-evaluator-functional-flutter` — `flutter analyze` + `flutter test` + build_runner drift + anti-pattern grep (FL-01~FL-08) |
-| Evaluator-Visual | **SKIP** (Flutter 앱은 브라우저 기반 시각 검증 불가) |
-| 레퍼런스 | API Layer Pattern, Riverpod Pattern, i18n Pattern, Anti-Patterns (9개 금지 패턴 + 셀프 체크 스크립트) |
+| 항목 | Web (`fe_target=web`) | Mobile/Desktop (`fe_target=mobile`/`desktop`) |
+|------|----------------------|---------------------------------------------|
+| Generator | `harness-generator-frontend-flutter` (Web 가이드 활성) | `harness-generator-frontend-flutter` (Mobile/Desktop 가이드) |
+| Eval-Func | **`harness-evaluator-functional`** (Playwright MCP) | `harness-evaluator-functional-flutter` (`flutter analyze` + `flutter test` + build_runner drift + FL-01~FL-08 정적 검증) |
+| Eval-Visual | **`harness-evaluator-visual`** (Playwright 스크린샷/반응형/접근성) | **SKIP** (브라우저 없음) |
+| 레퍼런스 공통 | API Layer Pattern, Riverpod Pattern, i18n Pattern, Anti-Patterns | 동일 |
+| 레퍼런스 추가 | **Flutter Web Pattern** (`dart:html`/`package:web` 허용, go_router, CORS, PWA, 빌드/호스팅) | — |
+| dart:html / package:web | **허용** (가능하면 conditional import 권장) | **금지** (모바일/데스크톱 빌드 실패 유발) |
+| 빌드 명령 | `flutter build web --release` / `flutter run -d chrome` | `flutter build apk` / `flutter build ios` / `flutter build macos` 등 |
 
-### FE 스택 감지
+### FE 스택 + 타겟 감지
 
-1. `scan-project.sh`가 `pubspec.yaml` + `flutter:` 키를 탐지
-2. Planner가 `pipeline.json.fe_stack = "flutter"` 확정
-3. `harness-next.sh`가 FE 에이전트를 자동 치환 (Agent Bar에도 반영)
+1. `scan-project.sh`가 `pubspec.yaml` + `flutter:` 키를 탐지하여 `fe_stack = "flutter"` 설정
+2. 같은 스캔이 `web/index.html`, `android/`, `ios/`, `macos/`/`windows/`/`linux/` 존재 여부로 `fe_target` 자동 판정 (`web` / `mobile` / `desktop`)
+3. Planner 가 모호한 경우(멀티 타겟, unknown) 사용자에게 단 한 번 확인하고 `pipeline.json.fe_target` 확정
+4. `harness-next.sh`가 `fe_stack + fe_target` 조합에 따라 FE 에이전트를 자동 치환 (Agent Bar에도 반영)
 
 ---
 
@@ -340,7 +345,7 @@ Evaluator-Functional / Evaluator-Visual이 브라우저 테스트를 수행하
 }
 ```
 
-> Flutter 프로젝트에서는 Playwright가 필요 없습니다 — `evaluator-functional-flutter`는 `flutter analyze` + `flutter test` 기반입니다.
+> **Flutter Web (`fe_target=web`) 프로젝트도 Playwright 가 필요합니다** — 컴파일 결과가 일반 웹앱과 동일하므로 React 와 같은 evaluator 를 재사용합니다. **Flutter Mobile/Desktop (`fe_target=mobile`/`desktop`) 프로젝트만** Playwright 없이 `flutter analyze` + `flutter test` 기반으로 동작합니다.
 
 ---
 
@@ -384,10 +389,29 @@ grep "flutter:" pubspec.yaml
 
 # 재스캔
 bash scripts/scan-project.sh .
-# pipeline.json의 fe_stack 값 확인
-cat .harness/actions/pipeline.json | jq '.fe_stack'
+# pipeline.json의 fe_stack + fe_target 값 확인
+cat .harness/actions/pipeline.json | jq '.fe_stack, .fe_target'
 ```
 
+### Flutter Web 프로젝트인데 evaluator-functional-flutter (정적 분석) 가 실행돼요
+
+`fe_target` 이 `web` 으로 감지되지 않아서 발생합니다. 다음 두 가지를 확인:
+
+```bash
+# 1) Flutter 프로젝트 루트에 web/index.html 이 존재하는가?
+ls -la web/index.html
+# 없으면 Flutter Web 활성화:
+flutter config --enable-web
+flutter create --platforms=web .
+
+# 2) pipeline.json 의 fe_target 값 확인
+jq '.fe_target' .harness/actions/pipeline.json
+# "mobile" 또는 "unknown" 이면 수동 수정 또는 재스캔
+bash scripts/scan-project.sh .
+```
+
+`fe_target = web` 으로 확정되면 Playwright 기반 `evaluator-functional` + `evaluator-visual` 이 자동 사용됩니다.
+
 ### Auto-routing을 끄고 싶어요
 
 ```json

package/assets/templates/AGENTS.md.template

@@ -50,3 +50,34 @@
 - 서비스 간 직접 DB 접근
 - 테스트 삭제/약화
 - archive/ 내 파일 수정
+- 아티팩트 상태가 `draft` 미만인 선행 아티팩트에 의존하여 작업 시작
+
+### 품질 게이트 (v3.1)
+
+| 게이트 | 시점 | 내용 |
+|--------|------|------|
+| **Pre-Eval Gate** | Generator → Evaluator 전환 | tsc, eslint, jest/vitest 자동 실행. 실패 시 Generator 리라우팅 |
+| **파일 소유권 검증** | 에이전트 전환 시 | git diff로 권한 밖 파일 수정 감지 |
+| **아티팩트 선행조건** | 에이전트 시작 전 | progress.json.artifacts 상태 확인 |
+| **에스컬레이션** | 3회 연속 실패 | Planner에게 scope 축소/접근 변경 요청 |
+
+### Evaluation System (v3.2)
+
+| 설정 | 값 |
+|------|------|
+| PASS 기준 | **2.80 / 3.00 이상** |
+| FAIL 기준 | 2.79 이하 (예외 없음) |
+| Evidence 없는 Score | 0점 강제 |
+| AC 부분 통과 | FAIL (100% 필수) |
+| Regression 실패 1건+ | FAIL (신규 점수 무관) |
+
+- Planner는 feature-list.json에 **Executable AC** (type: api/visual/e2e + verify 조건) 필수 작성
+- Evaluator는 Adversarial Rules에 따라 적대적으로 검증 (rubber-stamping 금지)
+- 이전 Sprint PASS 기능은 Regression Checkpoint로 재검증
+- Eval-Functional ↔ Eval-Visual 간 Cross-Validation으로 불일치 감지
+
+### 메모리 오염 방어
+
+- gotcha/memory 항목은 `unverified` 상태로 시작, Planner 리뷰 후 `verified` 승격
+- TTL 만료 항목은 Planner 스프린트 전환 시 리뷰 (갱신 또는 삭제)
+- 코드/git으로 검증 불가한 항목은 즉시 삭제

package/assets/templates/HARNESS.md

@@ -69,11 +69,68 @@ Planner → Gen-BE → Eval-Func(API-only) → Archive
 ### 공통 — 실패 시 루프
 
 ```
-Eval-Func FAIL → failure_location에 따라 Gen-BE 또는 Gen-FE 재작업 (max 10회)
-Eval-Visual FAIL → Gen-FE 재작업 (max 10회)
-10회 초과 → 사용자 개입 요청
+Eval-Func FAIL → failure_location에 따라 Gen-BE 또는 Gen-FE 재작업 (max 5회)
+Eval-Visual FAIL → Gen-FE 재작업 (max 5회)
+3회 실패 → Planner 에스컬레이션 (scope 축소/접근 변경)
+5회 초과 → 사용자 개입 요청
 ```
 
+### Pre-Eval Gate (Deterministic Checks)
+
+Generator → Evaluator 전환 전, 결정론적 검증을 자동 실행합니다:
+
+```
+Generator 완료 → [tsc --noEmit] → [eslint] → [jest/vitest --bail] → Evaluator
+                  ↓ FAIL                                              
+                  Generator로 리라우팅 (Evaluator 세션 미개설)
+```
+
+- Backend: `tsc --noEmit`, `eslint . --max-warnings=0`, `jest --bail`
+- Frontend: `tsc --noEmit`, `eslint . --max-warnings=0`, `vitest run --bail 1`
+- `config.json`의 `flow.pre_eval_gate`에서 커스터마이징 가능
+
+### Runtime Guardrail (파일 소유권 검증)
+
+에이전트 전환 시 `git diff`로 이전 에이전트가 권한 밖 파일을 수정했는지 검증합니다.
+위반 발견 시 경고를 출력하고 리뷰를 요청합니다.
+
+### Context Isolation Guard (컨텍스트 분리 가드레일)
+
+한 세션에서 여러 에이전트를 실행하면 컨텍스트가 오염됩니다.
+`UserPromptSubmit` 훅이 다음 위반을 실시간 감지합니다:
+
+- `current_agent`가 running인데 다른 `/harness-*` 스킬 호출 시 경고 주입
+- `agent_status`를 completed로 변경하지 않고 다음 에이전트 호출 시 경고
+
+### Statusline (상시 상태 표시)
+
+터미널 하단에 항상 고정되는 1줄 compact 상태:
+
+```
+[S1] FULL | >backend | 2/5 feat | ctx 45% | $1.23
+```
+
+- `scripts/harness-statusline.sh`가 3초 간격으로 `progress.json`을 읽어 갱신
+- `.claude/settings.json`의 `statusLine` 설정으로 활성화
+- 세션 시작 시 장황한 프로그래스 출력 대신 statusline으로 대체
+
+### Artifact State Machine
+
+주요 아티팩트는 상태를 추적합니다:
+
+```
+pending → draft → reviewed → approved
+```
+
+| 아티팩트 | 생성 에이전트 | 필수 상태 (다음 에이전트 진행 조건) |
+|----------|-------------|----------------------------------|
+| plan.md | Planner | draft 이상 → Generator |
+| api-contract.json | Planner | draft 이상 → Generator |
+| feature-list.json | Planner | draft 이상 → Generator |
+| sprint-contract.md | Generator | draft 이상 → Evaluator |
+
+상태는 `progress.json.artifacts`에서 추적됩니다.
+
 ## 세션 오케스트레이션
 
 ### 핵심: 한 세션에 1 에이전트 단계
@@ -117,12 +174,42 @@ claude --prompt "$(cat .harness/next-prompt.txt)"
 
 모든 에이전트 스킬에 내장된 프로토콜:
 
-- **On Start**: `progress.json` 읽기 → `agent_status: "running"` 설정
-- **On Complete**: `progress.json` 업데이트 → `next_agent` 계산 → **STOP**
+- **On Start**: `progress.json` 읽기 → `agent_status: "running"` 설정 → `handoff.json` 참조
+- **On Complete**: `progress.json` 업데이트 → 아티팩트 상태 갱신 → `next_agent` 계산 → **STOP**
 - **On Fail** (Evaluator): `failure` 정보 기록 → `retry_target` 설정 → **STOP**
+- **On Transition**: 파일 소유권 검증 → Pre-Eval Gate (해당 시) → 아티팩트 선행조건 검증
 
 에이전트는 절대 다음 에이전트를 직접 호출하지 않습니다.
 
+### Handoff Document
+
+에이전트 전환 시 `.harness/handoff.json`이 자동 생성됩니다:
+
+```json
+{
+  "from": "planner",
+  "to": "generator-backend",
+  "sprint": 1,
+  "retry_count": 0,
+  "sprint_status": "running",
+  "failure_context": null,
+  "artifacts_ready": ["plan.md", "api-contract.json", "feature-list.json"],
+  "focus_features": ["F-001", "F-002"],
+  "warnings": [],
+  "timestamp": "2026-04-09T12:00:00Z"
+}
+```
+
+각 에이전트는 세션 시작 시 이 파일을 읽어 컨텍스트를 확보합니다.
+
+### Escalation Protocol
+
+```
+1-2회 실패: 동일 에이전트 재시도 (실패 원인 요약 포함)
+3회 실패:   Planner 에스컬레이션 (scope 축소 또는 접근 변경)
+5회 실패:   BLOCKED — 사용자 개입 요청
+```
+
 ## 핵심 원칙
 
 1. **Backend First** — API가 안정된 후 Frontend 연동 (없는 API 호출 방지)
@@ -130,10 +217,97 @@ claude --prompt "$(cat .harness/next-prompt.txt)"
 3. **한 세션에 1 에이전트 단계** — 컨텍스트 소진 방지, Session Boundary Protocol 준수
 4. **feature-list.json의 passes만 수정** — 기능 정의는 Planner만 변경
 5. **테스트 삭제/약화 금지** — 테스트는 계약이다
-6. **Evaluator는 회의적** — 자기 설득 금지, 기준 미달 = FAIL
+6. **Evaluator는 적대적** — Rubber-stamping 금지, 2.80/3.00 미만 = FAIL, Evidence 없는 Score = 0
 7. **아카이브 불변** — 완료 문서 수정 금지
 8. **MSA 경계 존수** — 서비스 간 직접 DB 접근 금지, 반드시 메시지 패턴
 
+## Evaluation System (v3.2)
+
+### 정량 채점 (Rubric Scoring)
+
+모든 Evaluator는 구조화된 Rubric으로 채점합니다:
+
+| 설정 | 값 |
+|------|------|
+| 척도 | 0-3 (항목별) |
+| PASS 기준 | **2.80 / 3.00 이상** |
+| FAIL 기준 | 2.79 이하 (예외 없음) |
+| Evidence 없는 항목 | Score = 0으로 강제 재계산 |
+
+### Evaluator-Functional 채점 항목 (R1-R5)
+
+| # | Criterion | Weight |
+|---|-----------|--------|
+| R1 | API Contract 준수 | 25% |
+| R2 | Acceptance Criteria 전수 통과 | 25% |
+| R3 | 부정 테스트 (엔드포인트당 2개+) | 20% |
+| R4 | E2E 시나리오 (Playwright) | 15% |
+| R5 | 에러 핸들링 & 엣지케이스 | 15% |
+
+### Evaluator-Visual 채점 항목 (V1-V5)
+
+| # | Criterion | Weight |
+|---|-----------|--------|
+| V1 | 레이아웃 정확성 | 20% |
+| V2 | 반응형 (375/768/1280px) | 20% |
+| V3 | 접근성 WCAG 2.1 AA | 20% |
+| V4 | 시각적 일관성 + AI슬롭 감지 | 20% |
+| V5 | 인터랙션 상태 (로딩/에러/빈/호버/포커스) | 20% |
+
+### 자동 FAIL 조건 (Verdict Rules)
+
+어떤 상황에서도 아래 조건 충족 시 FAIL:
+
+1. Weighted Score < 2.80
+2. AC 100% 미통과 (부분 통과 불인정)
+3. Regression 실패 1건 이상 (신규 점수 무관)
+4. Evidence 누락 항목 존재 → 해당 Score = 0 재계산
+5. Cross-Validation 불일치 1건 이상 → CONDITIONAL FAIL
+6. (Visual) a11y Critical/Serious 위반 1건 이상 → V3 = 0
+7. (Visual) AI Slop 2건 이상 → V4 최대 1점
+
+### Executable Acceptance Criteria
+
+Planner는 feature-list.json에 기능을 정의할 때 **실행 가능한 검증 조건(AC)**을 반드시 작성합니다:
+
+```json
+{
+  "id": "AC-001",
+  "description": "유효한 이메일로 가입 시 201 응답",
+  "type": "api",
+  "verify": {
+    "method": "POST",
+    "path": "/api/auth/register",
+    "body": { "email": "test@test.com", "password": "Test1234!" },
+    "expect": { "status": 201 }
+  }
+}
+```
+
+AC 타입: `api` (HTTP 요청), `visual` (UI 요소 존재), `e2e` (사용자 플로우)
+
+### Regression Checkpoint
+
+Sprint N의 Evaluator는 이전 Sprint에서 PASS된 AC를 재검증합니다:
+- archive에서 이전 feature-list.json의 passed AC를 로드
+- handoff.json의 `regression` 필드로 전달
+- **1건이라도 회귀 실패하면 전체 FAIL**
+
+### Cross-Validation
+
+Eval-Functional의 결과를 Eval-Visual이 교차 검증합니다:
+- evaluation-functional.md 내 JSON 블록 → handoff.json의 `cross_validation_from_functional`
+- API 성공인데 UI에 에러 표시 = 불일치 = FAIL 사유
+
+### Adversarial Rules (적대적 행동 규칙)
+
+Evaluator 에이전트에게 강제되는 행동 규칙:
+- Generator의 '완료' 주장을 신뢰하지 않고 직접 검증
+- 정상 1개당 비정상 2개 이상 테스트
+- PASS 전 자문: "내가 이 코드로 PR을 올리겠는가?"
+- '전반적으로 잘 되었습니다' 류의 모호한 긍정 평가 **금지**
+- '시간 제약상 일부만 테스트' **금지** — 전수 불가 시 FAIL 처리
+
 ## Tech Stack
 
 | 영역 | 기술 |

package/assets/templates/config.json

@@ -1,7 +1,7 @@
 {
   "harness": {
     "name": "6-Agent Production Harness",
-    "version": "3.0.0",
+    "version": "3.2.0",
     "description": "Dispatcher + NestJS MSA + React/Next.js + Playwright 기반 실무 하네스",
     "source": "https://www.anthropic.com/engineering/harness-design-long-running-apps"
   },
@@ -13,12 +13,25 @@
       "always_first": true
     },
     "brainstorming": {
-      "role": "사용자의 러프한 요구사항을 대화형으로 구체화하여 Planner가 바로 쓸 수 있는 brainstorm-spec.md로 변환. Dispatcher가 사용자에게 '브레인스토밍 필요?' 확인 후에만 호출되는 조건부 에이전트.",
+      "role": "사용자의 러프한 요구사항을 대화형으로 구체화하여 Planner가 바로 쓸 수 있는 brainstorm-spec.md로 변환.",
       "skill": "harness-brainstorming",
       "inputs": ["(user conversation)"],
       "outputs": ["actions/brainstorm-spec.md"],
       "conditional": true,
-      "invoked_by": "dispatcher (user opt-in)",
+      "trigger_conditions": {
+        "comment": "Dispatcher가 아래 조건 중 하나 이상 충족 시 사용자에게 브레인스토밍 제안",
+        "rules": [
+          "사용자 요청에 구체적 기능명/엔드포인트/화면명이 없고 추상적 목표만 있을 때",
+          "PRD/OpenAPI 등 구조화된 입력 문서가 없을 때",
+          "'뭔가 만들고 싶은데', '아이디어가 있는데' 등 탐색적 표현이 포함될 때"
+        ],
+        "skip_when": [
+          "사용자가 PRD, OpenAPI spec, 또는 구체적 feature list를 제공한 경우",
+          "사용자가 '브레인스토밍 없이', 'skip brainstorming'을 명시한 경우",
+          "이미 brainstorm-spec.md가 actions/에 존재하는 경우"
+        ]
+      },
+      "invoked_by": "dispatcher (user opt-in after suggestion)",
       "next_on_complete": "planner",
       "attribution": "Derived from obra/superpowers skills/brainstorming (MIT License)"
     },
@@ -50,15 +63,55 @@
       "role": "Playwright로 E2E 기능 검증, API 응답/DB 상태 확인",
       "skill": "harness-evaluator-functional",
       "tools": ["playwright:browser_*"],
-      "inputs": ["actions/sprint-contract.md"],
-      "outputs": ["actions/evaluation-functional.md"]
+      "inputs": ["actions/sprint-contract.md", "actions/feature-list.json", "actions/api-contract.json"],
+      "outputs": ["actions/evaluation-functional.md"],
+      "evaluation_template": "assets/templates/evaluation-functional.md.template",
+      "adversarial_rules": {
+        "comment": "Evaluator 적대적 행동 규칙 — 통과 편향 제거를 위한 강제 규칙",
+        "rules": [
+          "Generator의 '구현 완료' 주장을 절대 신뢰하지 마라. 모든 엔드포인트에 직접 요청을 보내고 응답을 확인하라.",
+          "정상 경로(happy path) 1개당 비정상 경로(unhappy path) 최소 2개를 반드시 테스트하라.",
+          "api-contract.json과 실제 응답을 필드 단위로 비교하라. 누락 필드, 타입 불일치, 추가 필드 모두 FAIL 사유.",
+          "PASS를 주기 전에 자문하라: '내가 이 코드를 직접 작성했다면 이 수준으로 PR을 올리겠는가?' NO이면 FAIL.",
+          "AC 항목 하나라도 미통과이면 전체 FAIL. 부분 통과는 인정하지 않는다.",
+          "Evidence(증거)가 없는 Score는 0점이다. '확인했다'는 주장은 증거가 아니다.",
+          "이전 Sprint에서 PASS된 기능이 하나라도 깨졌으면 신규 기능 점수와 무관하게 FAIL.",
+          "Score 3을 주려면 엣지케이스(빈 값, 초과값, 동시 요청, 특수문자)까지 테스트한 증거가 있어야 한다."
+        ],
+        "forbidden": [
+          "'전반적으로 잘 구현되었습니다' 류의 모호한 긍정 평가",
+          "'사소한 이슈이므로 PASS' — 사소함은 Evaluator가 판단할 사항이 아니다",
+          "'시간 제약상 일부만 테스트' — 전수 테스트가 불가하면 FAIL 처리",
+          "Generator에게 유리한 방향으로 기준을 해석하는 행위"
+        ]
+      }
     },
     "evaluator-visual": {
       "role": "디자인 일관성, 반응형, 접근성, AI슬롭 감지",
       "skill": "harness-evaluator-visual",
       "tools": ["playwright:browser_take_screenshot", "playwright:browser_resize", "playwright:browser_snapshot"],
-      "inputs": ["actions/sprint-contract.md", "actions/evaluation-functional.md"],
-      "outputs": ["actions/evaluation-visual.md"]
+      "inputs": ["actions/sprint-contract.md", "actions/evaluation-functional.md", "actions/feature-list.json"],
+      "outputs": ["actions/evaluation-visual.md"],
+      "evaluation_template": "assets/templates/evaluation-visual.md.template",
+      "adversarial_rules": {
+        "comment": "Visual Evaluator 적대적 행동 규칙",
+        "rules": [
+          "모든 페이지를 반드시 3개 뷰포트(375px, 768px, 1280px)에서 스크린샷 촬영하라. 1개라도 누락이면 해당 페이지 Score 산정 불가.",
+          "axe-core 접근성 검사를 실제로 실행하라. Critical 또는 Serious 위반이 1건이라도 있으면 V3 = 0.",
+          "AI슬롭 패턴(무의미한 그라데이션, 과도한 그림자, 장식 아이콘 남발)을 적극 탐지하라. 2건 이상이면 V4 최대 1점.",
+          "evaluation-functional.md의 Cross-Validation Data와 교차 검증하라. API 성공인데 UI에 에러 표시 = 불일치 = FAIL 사유.",
+          "이전 Sprint 스크린샷 대비 의도치 않은 시각 변경이 있으면 점수 무관 FAIL.",
+          "PASS를 주기 전에 자문하라: '이 UI를 실사용자에게 보여줄 수 있는가?' NO이면 FAIL.",
+          "로딩/에러/빈 상태가 하나라도 미구현이면 V5 최대 1점.",
+          "Evidence(스크린샷 경로 또는 DOM 스냅샷)가 없는 Score는 0점이다."
+        ],
+        "forbidden": [
+          "'디자인이 깔끔합니다' 류의 주관적 긍정 평가",
+          "'접근성은 추후 개선' — 접근성은 기본 요건이지 부가 기능이 아니다",
+          "'모바일 뷰포트는 생략' — 3개 뷰포트 전수 검사는 필수",
+          "스크린샷 없이 '확인했다'고 주장하는 행위"
+        ]
+      }
     },
     "generator-frontend-flutter": {
       "role": "Flutter 앱 개발 — Riverpod, integrated_data_layer(Retrofit), i18n(ARB), build_runner",
@@ -87,11 +140,30 @@
         "BE-ONLY": ["planner", "generator-backend", "evaluator-functional:api-only"]
       },
       "fe_stack_substitution": {
-        "comment": "pipeline.json.fe_stack=flutter 이면 아래 치환을 적용. evaluator-visual은 skip.",
+        "comment": "pipeline.json.fe_stack + fe_target 에 따라 FE 에이전트 치환. Flutter Web 은 React 와 동일한 Playwright 기반 evaluator 를 사용한다.",
         "flutter": {
-          "generator-frontend": "generator-frontend-flutter",
-          "evaluator-functional": "evaluator-functional-flutter",
-          "evaluator-visual": "__skip__"
+          "_doc": "fe_target = web | mobile | desktop. by_target 으로 분기.",
+          "by_target": {
+            "web": {
+              "_doc": "Flutter Web — 컴파일 결과가 HTML+JS+CSS 이므로 Playwright evaluator 사용 가능",
+              "generator-frontend": "generator-frontend-flutter",
+              "evaluator-functional": "evaluator-functional",
+              "evaluator-visual": "evaluator-visual"
+            },
+            "mobile": {
+              "_doc": "Flutter Mobile (Android/iOS) — 브라우저 없음, 정적 분석 evaluator 사용",
+              "generator-frontend": "generator-frontend-flutter",
+              "evaluator-functional": "evaluator-functional-flutter",
+              "evaluator-visual": "__skip__"
+            },
+            "desktop": {
+              "_doc": "Flutter Desktop (macOS/Windows/Linux) — 브라우저 없음, 정적 분석 evaluator 사용",
+              "generator-frontend": "generator-frontend-flutter",
+              "evaluator-functional": "evaluator-functional-flutter",
+              "evaluator-visual": "__skip__"
+            }
+          },
+          "_default_target": "mobile"
         }
       }
     },
@@ -101,14 +173,133 @@
       "reason": "프론트가 존재하지 않는 API를 호출하는 실패 방지"
     },
     "retry_on_fail": true,
-    "max_retries_per_sprint": 10,
-    "archive_on_sprint_complete": true
+    "max_retries_per_sprint": 5,
+    "escalate_to_planner_after": 3,
+    "archive_on_sprint_complete": true,
+    "pre_eval_gate": {
+      "comment": "Generator → Evaluator 전환 전 결정론적 검증. 실패 시 Evaluator 세션을 열지 않고 Generator로 자동 리라우팅.",
+      "enabled": true,
+      "backend_checks": ["npx tsc --noEmit", "npx eslint . --max-warnings=0", "npx jest --bail --passWithNoTests"],
+      "frontend_checks": ["npx tsc --noEmit", "npx eslint . --max-warnings=0", "npx vitest run --bail 1"],
+      "timeout_seconds": 120,
+      "on_fail": "reroute_to_generator"
+    }
+  },
+  "evaluation": {
+    "comment": "Evaluator 공통 설정",
+    "scoring": {
+      "scale": 3,
+      "pass_threshold": 2.80,
+      "fail_threshold": 2.79,
+      "verdict_rules": [
+        "Weighted Score < 2.80 → FAIL",
+        "AC Pass Rate < 100% → FAIL (부분 통과 불인정)",
+        "Regression Failures > 0 → FAIL (신규 점수 무관)",
+        "Evidence 누락 항목 → 해당 Score = 0으로 재계산",
+        "Cross-Validation 불일치 > 0 → CONDITIONAL FAIL"
+      ]
+    },
+    "regression": {
+      "enabled": true,
+      "source": "archive",
+      "scope": "all_passed_features",
+      "comment": "이전 Sprint에서 PASS된 모든 AC를 현재 Sprint에서 재검증. 1건이라도 실패하면 전체 FAIL."
+    },
+    "cross_validation": {
+      "enabled": true,
+      "comment": "evaluator-functional과 evaluator-visual이 서로의 결과를 참조하여 불일치를 감지. evaluation-*.md의 Cross-Validation Data JSON 블록을 기계적으로 파싱."
+    },
+    "acceptance_criteria_schema": {
+      "comment": "Planner가 feature-list.json에 기능 정의 시 반드시 작성해야 하는 실행 가능한 검증 조건 스키마. Evaluator는 이 조건을 기계적으로 실행한다.",
+      "required_fields": ["id", "description", "type", "verify"],
+      "types": {
+        "api": {
+          "verify_fields": ["method", "path", "body", "expect"],
+          "expect_fields": ["status"],
+          "optional_expect": ["body_contains", "body_schema", "headers"]
+        },
+        "visual": {
+          "verify_fields": ["url", "elements"],
+          "optional_verify": ["viewport", "state", "screenshot_match"]
+        },
+        "e2e": {
+          "verify_fields": ["steps"],
+          "step_fields": ["action", "target", "value", "expect"]
+        }
+      },
+      "example": {
+        "id": "AC-001",
+        "description": "유효한 이메일로 가입 시 201 응답",
+        "type": "api",
+        "verify": {
+          "method": "POST",
+          "path": "/api/auth/register",
+          "body": { "email": "test-{{timestamp}}@test.com", "password": "Test1234!" },
+          "expect": { "status": 201, "body_contains": { "id": "string", "email": "string" } }
+        }
+      },
+      "negative_example": {
+        "id": "AC-002",
+        "description": "중복 이메일 시 409 응답",
+        "type": "api",
+        "verify": {
+          "method": "POST",
+          "path": "/api/auth/register",
+          "body": { "email": "duplicate@test.com", "password": "Test1234!" },
+          "expect": { "status": 409 }
+        },
+        "is_negative": true
+      },
+      "visual_example": {
+        "id": "AC-003",
+        "description": "회원가입 폼 렌더링 확인",
+        "type": "visual",
+        "verify": {
+          "url": "/register",
+          "elements": ["input[name=email]", "input[name=password]", "button[type=submit]"],
+          "viewport": [375, 768, 1280]
+        }
+      }
+    }
+  },
+  "artifacts": {
+    "comment": "아티팩트 상태 머신. 각 에이전트 실행 전 선행 아티팩트가 required_status 이상인지 검증.",
+    "states": ["pending", "draft", "reviewed", "approved"],
+    "prerequisites": {
+      "generator-backend": {
+        "plan.md": "draft",
+        "api-contract.json": "draft",
+        "feature-list.json": "draft"
+      },
+      "generator-frontend": {
+        "plan.md": "draft",
+        "api-contract.json": "draft",
+        "feature-list.json": "draft"
+      },
+      "evaluator-functional": {
+        "sprint-contract.md": "draft"
+      },
+      "evaluator-visual": {
+        "sprint-contract.md": "draft"
+      }
+    }
   },
   "session": {
     "isolation": true,
     "state_file": ".harness/progress.json",
     "state_log": ".harness/progress.log",
-    "next_prompt_file": ".harness/next-prompt.txt"
+    "next_prompt_file": ".harness/next-prompt.txt",
+    "handoff_file": ".harness/handoff.json",
+    "context_guard": {
+      "comment": "컨텍스트 분리 하드 가드레일. UserPromptSubmit 훅이 위반을 감지하면 경고를 주입한다.",
+      "enabled": true,
+      "rules": [
+        "current_agent가 running 상태일 때 다른 에이전트 스킬 호출 금지",
+        "한 세션에서 2개 이상의 에이전트 스킬 실행 금지",
+        "agent_status를 completed로 변경하지 않고 다음 에이전트를 호출하면 경고"
+      ],
+      "on_violation": "warn_and_block"
+    }
   },
   "behavior": {
     "comment": "하네스 동작 플래그. UserPromptSubmit 훅이 이 값을 읽어 자동 라우팅을 결정한다.",