@walwal-harness/cli 2.0.1 → 2.3.0

package/skills/dispatcher/SKILL.md

@@ -16,13 +16,31 @@ disable-model-invocation: false
 1. progress.json 업데이트:
    - `agent_status` → `"completed"`
    - `completed_agents`에 `"dispatcher"` 추가
-   - `next_agent` → `"planner"`
+   - `next_agent` → **브레인스토밍 결정 트리에 따라 결정** ([섹션 6](#6-brainstormer-routing-decision) 참조)
+     - 신규/재플래닝 + 사용자가 브레인스토밍 선택 → `"brainstorming"`
+     - 신규/재플래닝 + 사용자가 건너뛰기 선택 → `"planner"`
+     - 특정 에이전트 직접 명령 → 해당 에이전트 (예: `"evaluator-functional"`)
+     - Gotcha 교정 후 재작업 → `failure.retry_target` (해당 에이전트)
    - `pipeline` → 선택된 파이프라인 (FULLSTACK/FE-ONLY/BE-ONLY)
-   - `sprint.number` → `1`, `sprint.status` → `"in_progress"`
+   - `sprint.number` → `1`, `sprint.status` → `"in_progress"` (신규 파이프라인인 경우에만)
 2. `.harness/progress.log`에 요약 한 줄 추가
 3. **STOP. 다음 에이전트를 직접 호출하지 않는다.**
 4. 출력: `"✓ Dispatcher 완료. bash scripts/harness-next.sh 실행하여 다음 단계 확인."`
 
+## Auto-Routing (UserPromptSubmit Hook)
+
+walwal-harness v2.2.0+ 부터 **UserPromptSubmit 훅** 이 모든 사용자 프롬프트 앞에
+`[walwal-harness] Auto-routing is ACTIVE` 안내를 자동 주입한다. 이 훅이 켜져 있으면
+Claude 는 기본적으로 Dispatcher 경유로 분류/라우팅해야 한다.
+
+- **활성 조건**: `.harness/config.json` 의 `behavior.auto_route_dispatcher == true`
+- **per-message opt-out**: 사용자가 `harness skip`, `harness 없이`, `without harness`,
+  `just answer` 등을 말하면 그 메시지 한정으로 훅이 pass-through
+- **전역 비활성**: `behavior.auto_route_dispatcher = false`
+
+훅이 주입하는 컨텍스트에는 `pipeline`, `current_agent`, `next_agent`, `sprint`,
+`fe_stack` 현재값이 포함되므로 Dispatcher 는 별도 상태 조회 없이 판단 가능.
+
 ## 1. Request Classification (최우선)
 
 사용자 입력을 먼저 분류합니다:
@@ -30,6 +48,7 @@ disable-model-invocation: false
 - **실수 지적** ("아니", "잘못", "그렇게 하면 안 돼", "X로 해야지") → **Gotcha Flow**
 - **기능 요청** ("만들어", "추가", "시작", PRD, OpenAPI) → **Pipeline Flow**
 - **혼합** → Gotcha 먼저 기록 → Pipeline 이어서
+- **메타/인사/Claude 자체 질문** → Dispatcher skip, 짧은 일반 응답 허용
 
 ## 2. Gotcha Flow
 
@@ -68,3 +87,96 @@ AGENTS.md 비하네스  → 기존 백업 + 리빌드
 ## 5. Output
 
 `.harness/actions/pipeline.json` 생성 → 사용자 확인 → Session Boundary Protocol On Complete 실행
+
+### fe_stack 필드 (FE 파이프라인에서 필수)
+
+FE-ONLY 또는 FULLSTACK 선택 시, `pipeline.json`에 **`fe_stack`** 필드를 포함해야 한다:
+
+- `scan-result.json.tech_stack.fe_stack` 값을 기본으로 사용 (`react` | `flutter`)
+- 값이 없거나 불명확하면 Planner가 확정하도록 위임 (Dispatcher는 `"unknown"` 기록 + `notes` 에 메모)
+- Flutter 선택 시 `agents_active`/`agents_skipped`에 치환된 에이전트명을 기록
+  - active: `generator-frontend-flutter`, `evaluator-functional-flutter`
+  - skipped: `generator-frontend`, `evaluator-functional`, `evaluator-visual`
+
+## 6. Brainstormer Routing Decision
+
+**원칙**: Brainstormer 는 파이프라인의 고정 스텝이 **아니다**. Dispatcher 가 조건부로 삽입한다.
+
+### 6.1 결정 트리
+
+Dispatcher 는 사용자 요청을 분류한 뒤 아래 순서로 판단:
+
+```
+1. Gotcha / 실수 지적인가?
+   → YES: gotcha 기록 → next_agent = failure.retry_target (해당 에이전트)
+         (브레인스토밍 없음)
+
+2. 특정 에이전트 직접 명령인가?
+   ("evaluator 다시 돌려", "generator-frontend 재작업", "planner plan.md 고쳐" 등)
+   → YES: next_agent = <대상 에이전트> (브레인스토밍 없음)
+
+3. Planner 가 동작해야 하는 케이스인가?
+   (신규 파이프라인 / 신규 PRD / 기존 plan.md 대폭 수정 / 신규 feature 대규모 추가)
+   → YES: 사용자에게 확인 질문 → 6.2 "브레인스토밍 확인 플로우"
+   → NO:  다른 에이전트로 라우팅 (generator 이어서 등)
+
+4. 그 외 (메타/인사/Claude 자체 질문) → Dispatcher skip
+```
+
+### 6.2 브레인스토밍 확인 플로우
+
+Planner 를 호출해야 한다고 판단되면, **사용자에게 단 하나의 질문을 출력한 뒤 대기한다:**
+
+```
+이 요청은 Planner 가 처리할 신규/재플래닝 건으로 보입니다.
+러프한 요구사항을 먼저 구체화하는 Brainstormer 과정을 거칠까요?
+
+  (Y) 예 — Brainstormer 와 대화하며 요구사항을 fit 하게 만든 뒤 Planner
+  (N) 아니오 — 이미 PRD/OpenAPI 가 명확하므로 바로 Planner
+
+답변: Y / N
+```
+
+사용자 응답 처리:
+- **Y (긍정)** — "네", "y", "yes", "필요해", "해줘" 등
+  → `next_agent = "brainstorming"`
+- **N (부정)** — "아니오", "n", "no", "필요없어", "바로", "skip" 등
+  → `next_agent = "planner"`
+- **불명확 / 무응답** — 한 번 더 "Y 또는 N 으로 답해주세요" 요청
+
+### 6.3 Skip 케이스 정리
+
+브레인스토밍이 **실행되지 않는** 경우 (Dispatcher 가 직접 다른 에이전트로 라우팅):
+
+| 상황 | next_agent |
+|------|-----------|
+| "Eval, X 다시 검증해" | `evaluator-functional` (또는 `evaluator-visual`) |
+| "Generator-FE, Y 버그 고쳐" | `generator-frontend` (또는 Flutter 변형) |
+| "Generator-BE, API 재생성해" | `generator-backend` |
+| Eval FAIL → retry | `failure.retry_target` |
+| Gotcha 수정 | `failure.retry_target` 또는 현재 에이전트 |
+| 기존 plan.md 소폭 수정 (Dispatcher 판단) | `planner` (직접) |
+| 사용자가 "Brainstormer 없이" / "skip brainstorming" 명시 | `planner` (직접) |
+
+### 6.4 강제 호출 케이스
+
+사용자가 명시적으로 원하면 브레인스토밍은 언제든 재호출 가능:
+
+- "Brainstormer 다시 돌려줘"
+- "요구사항 다시 잡자"
+- "plan 처음부터"
+
+이 경우 기존 `.harness/actions/brainstorm-spec.md` 는 Brainstormer 의 On Start 에서
+`.harness/archive/brainstorm-spec-<timestamp>.md` 로 백업된다.
+
+## 7. Handoff 라우팅 (fe_stack 반영)
+
+Dispatcher가 `next_agent` 를 세팅할 때 pipeline.json.fe_stack 을 참조해 치환:
+
+| 원본 next_agent | fe_stack=react | fe_stack=flutter |
+|-----------------|----------------|------------------|
+| generator-frontend | generator-frontend | generator-frontend-flutter |
+| evaluator-functional (FE 단계) | evaluator-functional | evaluator-functional-flutter |
+| evaluator-visual | evaluator-visual | (skip → 다음 단계로 이동) |
+
+**Brainstormer 는 fe_stack 치환 대상이 아니다** — 언어/스택 무관 공통 에이전트.

package/skills/dispatcher/references/pipeline-definitions.md

@@ -1,5 +1,52 @@
+---
+docmeta:
+  id: pipeline-definitions
+  title: Pipeline Definitions
+  type: output
+  createdAt: 2026-04-09T00:00:00Z
+  updatedAt: 2026-04-09T00:00:00Z
+  source:
+    producer: agent
+    skillId: harness-dispatcher
+  inputs:
+    - documentId: harness-dispatcher-skill
+      uri: ../SKILL.md
+      relation: output-from
+      sections:
+        - sourceRange:
+            startLine: 58
+            endLine: 70
+          targetRange:
+            startLine: 30
+            endLine: 95
+  tags:
+    - dispatcher
+    - pipeline
+    - fe-stack
+    - flutter
+---
+
 # Pipeline Definitions
 
+> **FE Stack 차원**: 모든 FE 관련 파이프라인은 `fe_stack` 필드로 React/Flutter를 구분한다.
+> Planner가 scan-result.json(`tech_stack.fe_stack`) 또는 사용자 질문으로 확정한다.
+
+## fe_stack 스위치 매트릭스
+
+| fe_stack | FE Generator | FE Evaluator(Functional) | Evaluator-Visual |
+|----------|--------------|--------------------------|------------------|
+| `react`  | `generator-frontend` | `evaluator-functional` (Playwright MCP) | `evaluator-visual` |
+| `flutter`| `generator-frontend-flutter` | `evaluator-functional-flutter` (flutter analyze/test) | **SKIP** (브라우저 없음) |
+
+Dispatcher는 `next_agent`를 설정할 때 다음 규칙으로 치환한다:
+
+```
+if pipeline.json.fe_stack == "flutter":
+    "generator-frontend"  → "generator-frontend-flutter"
+    "evaluator-functional" (FE 단계) → "evaluator-functional-flutter"
+    "evaluator-visual" → skip (agents_skipped로 이동)
+```
+
 ## FE-ONLY
 
 ```yaml
@@ -7,16 +54,17 @@ trigger: 외부 API 존재 + FE 작업 요청
 agents:
   - planner (light):
       skip: MSA 서비스 설계, BE 기능 목록
-      do: OpenAPI → api-contract.json 변환, FE 컴포넌트 설계, feature-list (layer: frontend만)
-  - generator-frontend
-  - evaluator-functional
-  - evaluator-visual
+      do: OpenAPI → api-contract.json 변환, FE 컴포넌트 설계, feature-list (layer: frontend만), fe_stack 확정
+  - generator-frontend OR generator-frontend-flutter  # fe_stack에 따라
+  - evaluator-functional OR evaluator-functional-flutter
+  - evaluator-visual  # fe_stack == "flutter" 이면 SKIP
 skip:
   - generator-backend
 notes:
   - api-contract.json은 OpenAPI에서 파생 (Planner가 변환)
-  - Eval-Func의 API Health Check는 외부 서버 대상
+  - Eval-Func(React)의 API Health Check는 외부 서버 대상
   - AGENTS.md IA-MAP에 BE 경로 없음 (외부 서버)
+  - fe_stack=flutter 인 경우 evaluator-visual 생략
 ```
 
 ## BE-ONLY

package/skills/evaluator-functional-flutter/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: harness-evaluator-functional-flutter
+description: "하네스 Flutter Functional Evaluator. Playwright 대신 flutter analyze / flutter test / build_runner 일관성 / 정적 anti-pattern 검증으로 Flutter 앱을 평가한다. Step 0 IA Gate → Step 1-6 정적/동적 검증. 기준 미달 = FAIL."
+disable-model-invocation: true
+---
+
+# Evaluator-Functional-Flutter — Dart/Flutter 정적·동적 검증
+
+> **주의**: Flutter 앱은 브라우저가 아니므로 Playwright MCP(`browser_*`)를 쓸 수 없다.
+> 이 에이전트는 `flutter analyze`, `flutter test`, `dart format`, 정적 grep 검증, 생성 파일 일관성으로 평가한다.
+> 실기기/시뮬레이터 UI 검증은 사람 QA 또는 별도 파이프라인으로 위임.
+
+## Session Boundary Protocol
+
+### On Start
+1. `.harness/progress.json` 읽기 — `next_agent`가 `"evaluator-functional-flutter"`인지 확인
+2. `.harness/actions/pipeline.json.fe_stack == "flutter"` 재확인 — 아니면 즉시 STOP + 불일치 보고
+3. progress.json 업데이트: `current_agent` → `"evaluator-functional-flutter"`, `agent_status` → `"running"`, `updated_at` 갱신
+
+### On Complete (PASS)
+1. progress.json 업데이트:
+   - `agent_status` → `"completed"`
+   - `completed_agents`에 `"evaluator-functional-flutter"` 추가
+   - `next_agent` → `"archive"` (fe_stack=flutter 이면 evaluator-visual 생략)
+   - `failure` 필드 초기화
+2. `feature-list.json`의 통과 feature `passes`에 `"evaluator-functional-flutter"` 추가
+3. `.harness/progress.log`에 PASS 요약 추가
+4. **STOP. 다음 에이전트를 직접 호출하지 않는다.**
+5. 출력: `"✓ Evaluator-Functional-Flutter PASS. bash scripts/harness-next.sh 실행하여 다음 단계 확인."`
+
+### On Fail
+1. progress.json 업데이트:
+   - `agent_status` → `"failed"`
+   - `failure.agent` → `"evaluator-functional-flutter"`
+   - `failure.location` → `"frontend"` (Flutter 앱은 항상 FE 재작업)
+   - `failure.message` → 실패 요약 (1줄)
+   - `failure.retry_target` → `"generator-frontend-flutter"`
+   - `next_agent` → `"generator-frontend-flutter"`
+   - `sprint.retry_count` 증가
+2. `sprint.retry_count >= 10`이면 `agent_status` → `"blocked"`, 사용자 개입 요청
+3. `.harness/progress.log`에 FAIL 요약 추가
+4. **STOP.**
+5. 출력: `"✖ Evaluator-Functional-Flutter FAIL. bash scripts/harness-next.sh 실행하여 재작업 대상 확인."`
+
+## Critical Mindset
+
+- **회의적 평가자**. Generator의 자체 평가를 신뢰하지 말고 직접 돌려라.
+- `flutter analyze` 경고가 있으면 "사소하다"고 자기 설득 금지 — 기준 미달.
+- 코드 읽기만으로 PASS 판정 금지 — **반드시 `flutter analyze` + `flutter test` 실행**.
+- 기준 미달 = FAIL. 예외 없음.
+
+## Startup
+
+1. `AGENTS.md` 읽기 — IA-MAP (Flutter 경로 확인)
+2. `.harness/gotchas/evaluator-functional-flutter.md` (없으면 skip) — **과거 실수 반복 금지**
+3. `actions/sprint-contract.md` — FE 성공 기준
+4. `actions/feature-list.json` — 이번 스프린트 범위 (`layer: "frontend"` + `fe_stack: "flutter"`)
+5. `actions/api-contract.json` — 기대 API 계약 (Retrofit 매핑 대조용)
+6. `.harness/progress.json`
+7. **Generator의 anti-patterns.md 로드** — 정적 검증 rule 소스
+   → `skills/generator-frontend-flutter/references/anti-patterns.md`
+
+## Evaluation Steps
+
+### Step 0: IA Structure Compliance (GATE)
+
+AGENTS.md IA-MAP vs 실제 구조 대조. **미통과 시 이하 전체 SKIP, 즉시 FAIL.**
+
+상세 → [IA 검증 가이드](references/ia-compliance.md)
+
+### Step 1: `flutter analyze` (정적 분석)
+
+```bash
+# 프로젝트 루트 또는 integrated_data_layer 하위에서
+flutter analyze --no-fatal-infos
+```
+
+- **warning / error 1개 이상 → FAIL**
+- info 수준은 허용 (하지만 evaluation 보고서에 카운트 기록)
+
+### Step 2: `flutter test` (단위/위젯 테스트)
+
+```bash
+# integrated_data_layer 테스트
+cd <integrated_data_layer 경로>
+flutter test
+
+# 앱 테스트 (존재 시)
+cd <app 루트>
+flutter test
+```
+
+- **실패 1개 이상 → FAIL**
+- 이번 스프린트에서 추가된 Request Body / Response에 `fromJson`/`toJson` 왕복 테스트 **존재 확인**
+  - 누락 시 → FAIL (Coverage gate)
+
+### Step 3: build_runner 일관성
+
+```bash
+cd <integrated_data_layer 경로>
+flutter pub run build_runner build --delete-conflicting-outputs
+git diff --name-only
+```
+
+- 재생성 후 `*.g.dart` diff 가 발생하면 → **FAIL** (Generator가 수동 편집 또는 재생성 누락)
+
+### Step 4: Anti-Pattern 정적 검증
+
+`skills/generator-frontend-flutter/references/anti-patterns.md` 의 **"셀프 체크 스크립트"** 섹션을
+그대로 실행한다. 하나라도 결과가 있으면 → **FAIL**.
+
+상세 → [정적 검증 룰](references/static-check-rules.md)
+
+### Step 5: API Contract Compliance
+
+`api-contract.json` 의 엔드포인트 vs `rest_api.dart` 의 Retrofit 어노테이션 대조:
+
+- 계약에 있는 모든 엔드포인트가 `rest_api.dart` 에 존재하는가
+- method, path, path param, body 타입이 일치하는가
+- Response 타입이 계약 스키마와 구조적으로 일치하는가 (필드 존재 + nullable 여부)
+- **불일치 1개 이상 → FAIL**
+
+### Step 6: Sprint Contract Criteria
+
+`sprint-contract.md` 의 FE 성공 기준을 순서대로 검증:
+
+- 새 페이지가 `xxx_page.dart` + `xxx_page_vm.dart` 쌍으로 존재하는가
+- VM이 `NotifierProvider` 를 사용하는가
+- i18n 키가 모든 arb 파일에 등록되었는가
+- 기준별 PASS/FAIL 기록 → 충족률 계산
+
+## Scoring
+
+| 차원 | 가중치 | 하드 임계값 | 측정 방법 |
+|------|--------|------------|----------|
+| Static Analysis | 25% | warning/error 0개 | `flutter analyze` |
+| Test Pass Rate | 25% | 100% | `flutter test` |
+| API Contract 준수 | 25% | 100% | rest_api.dart vs api-contract.json |
+| Anti-Pattern 청결 | 15% | 위반 0건 | 정적 grep |
+| Contract Criteria 충족률 | 10% | 80% | sprint-contract 기준 |
+
+**어떤 차원이든 하드 임계값 미달 → 스프린트 FAIL**
+
+상세 채점 → [스코어링 루브릭](references/scoring-rubric.md)
+
+## evaluation-functional.md 출력
+
+```markdown
+# Flutter Functional Evaluation: Sprint [N]
+
+## Date: [날짜]
+## Verdict: PASS / FAIL
+## Attempt: [N] / 10
+## Stack: flutter
+
+## Step 0: IA Structure Compliance
+- Verdict: PASS / FAIL (GATE)
+
+## Step 1: Flutter Analyze
+- errors: [N]
+- warnings: [N]
+- infos: [N]
+
+## Step 2: Flutter Test
+- total: [N], passed: [N], failed: [N]
+- missing_roundtrip_tests: [목록]
+
+## Step 3: build_runner 일관성
+- drift: [none | 목록]
+
+## Step 4: Anti-Pattern
+| Rule | Count | Files |
+| dart:html | 0 | - |
+| print() | 0 | - |
+| Color(0x...) in 신규 | 0 | - |
+| bridges/ 신규 | 0 | - |
+| Text('한글') 신규 | 0 | - |
+
+## Step 5: API Contract Compliance
+| EP ID | Method + Path | Dart Match | Issues |
+
+## Step 6: Contract Criteria Results
+| # | Criterion | Result | Evidence |
+
+## Scores
+| Dimension | Score | Threshold | Status |
+
+## Failures Detail
+### [#N] [기준/항목]
+- **Expected**: ...
+- **Actual**: ...
+- **Recommendation**: ...
+```
+
+## After Evaluation
+
+- **PASS** → Session Boundary Protocol On Complete (PASS) 실행
+- **FAIL** → Session Boundary Protocol On Fail 실행 (retry_target = generator-frontend-flutter)

package/skills/evaluator-functional-flutter/references/ia-compliance.md

@@ -0,0 +1,77 @@
+---
+docmeta:
+  id: ia-compliance
+  title: IA Structure Compliance — Step 0 (Gate) for Flutter
+  type: output
+  createdAt: 2026-04-09T00:00:00Z
+  updatedAt: 2026-04-09T00:00:00Z
+  source:
+    producer: agent
+    skillId: harness-evaluator-functional-flutter
+  inputs:
+    - documentId: evaluator-functional-ia-compliance
+      uri: ../../evaluator-functional/references/ia-compliance.md
+      relation: output-from
+      sections:
+        - sourceRange:
+            startLine: 1
+            endLine: 37
+          targetRange:
+            startLine: 32
+            endLine: 120
+  tags:
+    - evaluator
+    - flutter
+    - ia-compliance
+    - gate
+---
+
+# IA Structure Compliance — Step 0 (Gate) for Flutter
+
+## 검증 방법
+
+```bash
+# 1. 실제 Flutter 구조 확인
+ls -R lib/ integrated_data_layer/lib/ 2>/dev/null
+
+# 2. git diff로 소유권 위반 검출 (이번 스프린트 범위)
+git log --name-only --pretty=format: HEAD~[sprint_commits].. | sort -u
+```
+
+## 검증 항목
+
+| 검증 | 판정 | 예시 |
+|------|------|------|
+| IA-MAP 경로가 실제 존재하는가 | 누락 → FAIL | `lib/ui/pages/` 미생성 |
+| IA-MAP에 없는 경로가 생겼는가 | 미등록 → DRIFT 기록 | `lib/services/` 무단 생성 |
+| `[FE]` 소유를 BE가 수정했는가 | 침범 → FAIL | `lib/ui/` BE 수정 |
+| `[META]`/`[HARNESS]` 침범 | 침범 → FAIL | `AGENTS.md` 수정 |
+| `pubspec.yaml` 의존성 추가가 계약 범위 내인가 | 범위 이탈 → DRIFT 기록 | 승인 없는 의존성 추가 |
+
+## Flutter 전용 추가 검증
+
+| 검증 | 판정 |
+|------|------|
+| `integrated_data_layer/lib/2_data_sources/remote/` 내 파일이 프로젝트 컨벤션(`request/body/`, `response/`, `rest_api.dart`)을 지키는가 | 위반 → FAIL |
+| `lib/ui/pages/` 내 새 페이지가 `xxx_page.dart` + `xxx_page_vm.dart` 쌍으로 존재하는가 | 파트너 누락 → FAIL |
+| `bridges/` 하위에 신규 파일이 추가되었는가 | 추가 → FAIL (레거시 금지) |
+| `lib/l10n/` 의 arb 파일 키 집합이 모든 언어에서 동일한가 | 불일치 → FAIL |
+
+## 판정 규칙
+
+- **경로 누락 / 소유권 침범 / 파트너 누락** → 즉시 FAIL, Step 1 이하 SKIP
+- **미등록 경로 (Drift)** → FAIL 아님, evaluation에 `## AGENTS.md Drift` 기록
+- **arb 키 불일치** → FAIL (i18n 원칙 위반)
+
+## Output (evaluation-functional.md에 포함)
+
+```markdown
+## Step 0: IA Structure Compliance
+- Verdict: PASS / FAIL (GATE)
+- IA-MAP paths checked: [N]개
+- Missing paths: [목록 또는 "none"]
+- Unregistered paths: [목록 또는 "none"]
+- Ownership violations: [목록 또는 "none"]
+- Page/VM pair check: [N pages checked, N missing partners]
+- arb key diff: [none | "app_ja.arb missing: cancel, confirm"]
+```

package/skills/evaluator-functional-flutter/references/scoring-rubric.md

@@ -0,0 +1,132 @@
+---
+docmeta:
+  id: scoring-rubric
+  title: Flutter Functional Evaluation 스코어링 루브릭
+  type: output
+  createdAt: 2026-04-09T00:00:00Z
+  updatedAt: 2026-04-09T00:00:00Z
+  source:
+    producer: agent
+    skillId: harness-evaluator-functional-flutter
+  inputs:
+    - documentId: react-evaluator-scoring-rubric
+      uri: ../../evaluator-functional/references/scoring-rubric.md
+      relation: output-from
+      sections:
+        - sourceRange:
+            startLine: 1
+            endLine: 53
+          targetRange:
+            startLine: 32
+            endLine: 160
+  tags:
+    - evaluator
+    - flutter
+    - scoring
+    - rubric
+---
+
+# Flutter Functional Evaluation 스코어링 루브릭
+
+## 차원별 채점
+
+| 차원 | 가중치 | 하드 임계값 | 측정 방법 |
+|------|--------|------------|----------|
+| Static Analysis | 25% | warning/error 0개 | `flutter analyze --no-fatal-infos` |
+| Test Pass Rate | 25% | 100% | `flutter test` 모든 스위트 |
+| API Contract 준수 | 25% | 100% | rest_api.dart vs api-contract.json 대조 — 불일치 즉시 FAIL |
+| Anti-Pattern 청결 | 15% | 위반 0건 | static-check-rules.md 의 FL-01 ~ FL-08 |
+| Contract Criteria 충족률 | 10% | 80% | sprint-contract.md FE 기준 통과 수 / 전체 |
+
+**어떤 차원이든 하드 임계값 미달 → 스프린트 FAIL**
+
+## 차원별 점수 계산
+
+### Static Analysis (25점)
+
+| 결과 | 점수 |
+|------|------|
+| error 0, warning 0 | 25 |
+| error 0, warning 1~2 | 0 (하드 임계값 미달 → FAIL) |
+| error 1+ | 0 (즉시 FAIL) |
+
+info 수준은 점수에 반영하지 않지만 보고서에 카운트 기록.
+
+### Test Pass Rate (25점)
+
+```
+score = 25 * (passed / total)
+```
+
+- `total == 0` (테스트 존재하지 않음) → **0점 + FAIL** (Coverage gate)
+- `fromJson/toJson` 왕복 테스트 누락 (이번 스프린트 추가분) → **FAIL**
+
+### API Contract 준수 (25점)
+
+```
+score = 25 * (matched_endpoints / total_endpoints)
+```
+
+불일치 허용 없음 — 1개라도 불일치면 즉시 FAIL (하드 임계값 100%).
+
+매칭 체크:
+- method (GET/POST/PUT/DELETE)
+- path (변수명 포함)
+- path param → `@Path(...)` 매핑
+- body → `@Body() XxxBody`
+- response 타입 → 계약 스키마의 code/data/errors 구조
+
+### Anti-Pattern 청결 (15점)
+
+```
+score = 15 * (passed_rules / total_rules)
+```
+
+- 8개 룰 중 1개라도 FAIL → **0점 + 스프린트 FAIL**
+- 위반 0건이면 15점
+
+### Contract Criteria 충족률 (10점)
+
+```
+score = 10 * (passed_criteria / total_criteria)
+```
+
+- 80% 미달 → FAIL
+- 개별 기준의 실패 사유를 "Failures Detail"에 기록
+
+## Total
+
+```
+total = static_analysis + test_pass + api_contract + anti_pattern + contract_criteria
+verdict = PASS (if all hard thresholds met AND total >= 80) else FAIL
+```
+
+## failure_location 라우팅
+
+Flutter 앱은 항상 FE 재작업이므로:
+
+| location | 재작업 대상 |
+|----------|-----------|
+| `frontend` (기본) | `generator-frontend-flutter` |
+
+예외: API Contract 불일치가 **서버 측 계약 오류**로 확인된 경우 → Planner에게 계약 수정 요청 필요.
+이 경우 evaluation에 `## Change Request` 섹션 추가.
+
+## evaluation-functional.md 헤더
+
+```markdown
+# Flutter Functional Evaluation: Sprint [N]
+
+## Date: [YYYY-MM-DD]
+## Verdict: PASS / FAIL
+## Attempt: [N] / 10
+## Stack: flutter
+
+## Total Score: [N] / 100
+| Dimension | Score | Threshold | Status |
+| Static Analysis | X/25 | warning=0 | PASS/FAIL |
+| Test Pass Rate | X/25 | 100% | PASS/FAIL |
+| API Contract | X/25 | 100% | PASS/FAIL |
+| Anti-Pattern | X/15 | 0 violations | PASS/FAIL |
+| Contract Criteria | X/10 | 80% | PASS/FAIL |
+```