@walwal-harness/cli 2.4.0 → 2.5.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/config.json

@@ -87,11 +87,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"
         }
       }
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@walwal-harness/cli",
-  "version": "2.4.0",
+  "version": "2.5.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"

package/scripts/harness-next.sh

@@ -41,17 +41,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,7 +67,7 @@ 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"
 }
 

package/scripts/lib/harness-render-progress.sh

@@ -286,12 +286,17 @@ render_agent_bar() {
 
   if [ ! -f "$PROGRESS" ] || [ ! -f "$CONFIG" ]; then return 1; fi
 
-  local pipeline current_agent fe_stack
+  local pipeline current_agent fe_stack fe_target
   pipeline=$(jq -r '.pipeline // "unknown"' "$PROGRESS")
   current_agent=$(jq -r '.current_agent // "none"' "$PROGRESS")
   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
+      fe_target=$(jq -r ".flow.pipeline_selection.fe_stack_substitution.${fe_stack}._default_target // \"web\"" "$CONFIG" 2>/dev/null || echo "web")
+    fi
   fi
 
   local completed_agents
@@ -305,10 +310,10 @@ render_agent_bar() {
   while IFS= read -r agent; do
     agent=$(echo "$agent" | sed 's/:.*//')  # strip mode suffix like :light, :api-only
 
-    # fe_stack 치환 적용
+    # fe_stack + fe_target 치환 적용
     if [ "$fe_stack" = "flutter" ]; then
       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.flutter.by_target[\"${fe_target}\"][\"${agent}\"] // \"${agent}\"" "$CONFIG" 2>/dev/null)
       if [ "$sub" = "__skip__" ]; then continue; fi
       agent="$sub"
     fi

package/scripts/scan-project.sh

@@ -62,11 +62,15 @@ fi
 
 # Frontend
 # Flutter 우선 감지 — pubspec.yaml 존재하면 Flutter 프로젝트로 판정 (TECH_LANG도 보정)
-FE_STACK="react"  # react | flutter (기본값은 react 계열)
+FE_STACK="react"   # react | flutter (기본값은 react 계열)
+FE_TARGET="web"    # web | mobile | desktop (Flutter 의 컴파일 타겟; React 는 항상 web)
+FLUTTER_ROOT=""    # Flutter 프로젝트 루트 경로 (web/mobile/desktop 감지용)
+
 if [ -f "${PROJECT_ROOT}/pubspec.yaml" ] && grep -q "flutter:" "${PROJECT_ROOT}/pubspec.yaml" 2>/dev/null; then
   TECH_FRONTEND="flutter"
   TECH_LANG="dart"
   FE_STACK="flutter"
+  FLUTTER_ROOT="${PROJECT_ROOT}"
 elif [ -f "${PROJECT_ROOT}/next.config.js" ] || [ -f "${PROJECT_ROOT}/next.config.ts" ] || [ -f "${PROJECT_ROOT}/next.config.mjs" ]; then
   TECH_FRONTEND="nextjs"
 elif [ -f "${PROJECT_ROOT}/vite.config.ts" ] || [ -f "${PROJECT_ROOT}/vite.config.js" ]; then
@@ -91,16 +95,41 @@ fi
 # Flutter 서브디렉토리 감지 (monorepo 또는 서브 프로젝트 케이스)
 if [ "$TECH_FRONTEND" = "unknown" ]; then
   # 대표적인 Flutter 서브폴더 이름을 얕게 탐색
-  for d in apps/mobile mobile clue_mobile_app flutter_app; do
+  for d in apps/mobile apps/web mobile clue_mobile_app flutter_app; do
     if [ -f "${PROJECT_ROOT}/${d}/pubspec.yaml" ] && grep -q "flutter:" "${PROJECT_ROOT}/${d}/pubspec.yaml" 2>/dev/null; then
       TECH_FRONTEND="flutter"
       TECH_LANG="dart"
       FE_STACK="flutter"
+      FLUTTER_ROOT="${PROJECT_ROOT}/${d}"
       break
     fi
   done
 fi
 
+# Flutter fe_target 감지 (web / mobile / desktop)
+# - web/index.html 존재 → web
+# - android/ 또는 ios/ 존재 + web/ 없음 → mobile
+# - macos/ 또는 windows/ 또는 linux/ 존재 + 위 둘 없음 → desktop
+# - 동시 존재 (멀티 타겟) → web 우선 (사용자가 Planner에서 변경 가능)
+if [ "$FE_STACK" = "flutter" ] && [ -n "$FLUTTER_ROOT" ]; then
+  HAS_WEB=false
+  HAS_MOBILE=false
+  HAS_DESKTOP=false
+  [ -f "${FLUTTER_ROOT}/web/index.html" ] && HAS_WEB=true
+  { [ -d "${FLUTTER_ROOT}/android" ] || [ -d "${FLUTTER_ROOT}/ios" ]; } && HAS_MOBILE=true
+  { [ -d "${FLUTTER_ROOT}/macos" ] || [ -d "${FLUTTER_ROOT}/windows" ] || [ -d "${FLUTTER_ROOT}/linux" ]; } && HAS_DESKTOP=true
+
+  if [ "$HAS_WEB" = "true" ]; then
+    FE_TARGET="web"
+  elif [ "$HAS_MOBILE" = "true" ]; then
+    FE_TARGET="mobile"
+  elif [ "$HAS_DESKTOP" = "true" ]; then
+    FE_TARGET="desktop"
+  else
+    FE_TARGET="unknown"
+  fi
+fi
+
 # Database
 if grep -rq "typeorm\|prisma\|sequelize\|knex" "${PROJECT_ROOT}/package.json" 2>/dev/null; then
   if grep -q "pg\|postgres" "${PROJECT_ROOT}/package.json" 2>/dev/null; then
@@ -225,6 +254,7 @@ cat > "$OUTPUT" << JSONEOF
     "backend": "${TECH_BACKEND}",
     "frontend": "${TECH_FRONTEND}",
     "fe_stack": "${FE_STACK}",
+    "fe_target": "${FE_TARGET}",
     "database": "${TECH_DB}",
     "monorepo": "${TECH_MONOREPO}",
     "language": "${TECH_LANG}"
@@ -282,7 +312,7 @@ echo "=== Scan Complete ==="
 echo "Output: ${OUTPUT}"
 echo ""
 echo "--- Summary ---"
-echo "Tech Stack: ${TECH_BACKEND} / ${TECH_FRONTEND} (fe_stack=${FE_STACK}) / ${TECH_DB}"
+echo "Tech Stack: ${TECH_BACKEND} / ${TECH_FRONTEND} (fe_stack=${FE_STACK}, fe_target=${FE_TARGET}) / ${TECH_DB}"
 echo "Monorepo: ${TECH_MONOREPO}"
 echo "OpenAPI: ${OPENAPI}"
 echo "Git: ${GIT_INIT} (${GIT_COMMITS} commits, branch: ${GIT_BRANCH})"

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

@@ -31,20 +31,31 @@ docmeta:
 > **FE Stack 차원**: 모든 FE 관련 파이프라인은 `fe_stack` 필드로 React/Flutter를 구분한다.
 > Planner가 scan-result.json(`tech_stack.fe_stack`) 또는 사용자 질문으로 확정한다.
 
-## fe_stack 스위치 매트릭스
+## fe_stack + fe_target 스위치 매트릭스
 
-| 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** (브라우저 없음) |
+| fe_stack | fe_target | FE 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` (정적 분석) | **SKIP** |
+| `flutter`| `desktop` | `generator-frontend-flutter` | `evaluator-functional-flutter` (정적 분석) | **SKIP** |
 
-Dispatcher는 `next_agent`를 설정할 때 다음 규칙으로 치환한다:
+> **Flutter Web**: 컴파일 결과가 HTML+JS+CSS 이므로 React 경로의 Playwright evaluator 가 정상 동작.
+> Generator-Frontend-Flutter 의 Self-Verification 에서 `flutter analyze` / `flutter test` /
+> `flutter build web --release` 가 이미 통과한 상태로 handoff 됨이 전제.
+
+Dispatcher는 `next_agent`를 설정할 때 `pipeline.json` 의 `fe_stack` + `fe_target` 두 값을 보고 치환한다:
 
 ```
 if pipeline.json.fe_stack == "flutter":
-    "generator-frontend"  → "generator-frontend-flutter"
-    "evaluator-functional" (FE 단계) → "evaluator-functional-flutter"
-    "evaluator-visual" → skip (agents_skipped로 이동)
+    "generator-frontend" → "generator-frontend-flutter"  (모든 fe_target 공통)
+
+    if fe_target == "web":
+        "evaluator-functional" → "evaluator-functional"  (그대로, Playwright 사용)
+        "evaluator-visual"     → "evaluator-visual"      (그대로)
+    elif fe_target in ("mobile", "desktop"):
+        "evaluator-functional" → "evaluator-functional-flutter"
+        "evaluator-visual"     → __skip__
 ```
 
 ## FE-ONLY

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

@@ -6,9 +6,16 @@ disable-model-invocation: true
 
 # Evaluator-Functional-Flutter — Dart/Flutter 정적·동적 검증
 
-> **주의**: Flutter 앱은 브라우저가 아니므로 Playwright MCP(`browser_*`)를 쓸 수 없다.
-> 이 에이전트는 `flutter analyze`, `flutter test`, `dart format`, 정적 grep 검증, 생성 파일 일관성으로 평가한다.
-> 실기기/시뮬레이터 UI 검증은 사람 QA 또는 별도 파이프라인으로 위임.
+> **이 에이전트는 `fe_target = mobile` 또는 `desktop` 일 때만 사용된다.**
+>
+> Flutter Mobile/Desktop 앱은 브라우저가 아니므로 Playwright MCP(`browser_*`)를 쓸 수 없다.
+> 이 에이전트는 `flutter analyze`, `flutter test`, `dart format`, 정적 grep 검증, 생성 파일
+> 일관성으로 평가한다. 실기기/시뮬레이터 UI 검증은 사람 QA 또는 별도 파이프라인으로 위임.
+>
+> **`fe_target = web` 인 Flutter Web 프로젝트는 이 에이전트가 아니라 일반 `evaluator-functional`
+> 과 `evaluator-visual` 이 Playwright 로 검증한다** (컴파일 결과가 HTML+JS+CSS 이므로).
+> 이 경우 Generator-Frontend-Flutter 의 Self-Verification 단계에서 `flutter analyze` /
+> `flutter test` / `flutter build web --release` 가 이미 통과했음이 전제된다.
 
 ## Session Boundary Protocol
 

package/skills/generator-frontend-flutter/SKILL.md

@@ -33,7 +33,10 @@ disable-model-invocation: true
 4. `pwd` + `.harness/progress.json` + `git log --oneline -20`
 5. `.harness/actions/api-contract.json` 읽기 — **서버 API 계약이 Source of Truth**
 6. `.harness/actions/feature-list.json` — `layer: "frontend"` 필터
-7. `pubspec.yaml` 확인 — Flutter 버전, Riverpod/Retrofit/json_serializable 의존성 존재 확인
+7. `.harness/actions/pipeline.json` 의 **`fe_target`** 확인 (`web` | `mobile` | `desktop`)
+   - 이 값에 따라 허용되는 API, 빌드 명령, 안티패턴이 달라진다 (아래 "fe_target 분기" 섹션 참조)
+8. `pubspec.yaml` 확인 — Flutter 버전, Riverpod/Retrofit/json_serializable 의존성 존재 확인
+   - `fe_target = web` 인 경우 `flutter config --enable-web` 활성화 + `web/index.html` 존재 확인
 
 ## AGENTS.md — 읽기 전용
 
@@ -60,7 +63,38 @@ Backend 코드, `.harness/`, `AGENTS.md` 수정 금지.
 | [API Layer Pattern](references/api-layer-pattern.md) | integrated_data_layer 구조, Request/Response, Retrofit | API 연동 시 |
 | [Riverpod Pattern](references/riverpod-pattern.md) | Page+VM 쌍, NotifierProvider, family 패턴 | 페이지/위젯 구현 시 |
 | [i18n Pattern](references/i18n-pattern.md) | ARB 파일, LocaleAssist, 키 네이밍 | 문자열 추가 시 |
-| [Anti-Patterns](references/anti-patterns.md) | 금지 API, 하드코딩, bridges/, StatefulWidget 직접 호출 | 구현 완료 후 셀프 체크 |
+| [Anti-Patterns](references/anti-patterns.md) | 금지 API, 하드코딩, bridges/, StatefulWidget 직접 호출 (fe_target 별 차이 포함) | 구현 완료 후 셀프 체크 |
+| [Flutter Web Pattern](references/flutter-web-pattern.md) | Web 전용 — `dart:html`/`package:web` 허용, 라우팅, 빌드, hosting | `fe_target = web` 일 때만 |
+
+## fe_target 분기
+
+`pipeline.json.fe_target` 에 따라 적용되는 규칙이 다르다:
+
+### `fe_target = web` (Flutter Web)
+
+- **빌드**: `flutter build web --release` / 개발 서버: `flutter run -d chrome`
+- **HTML/JS 인터롭 허용**: `dart:html`, `package:web`, `dart:js_interop` 사용 가능
+  - 단, 가능하면 cross-platform 코드를 우선하고 web 전용 코드는 `if (kIsWeb)` 가드 또는 conditional import
+- **라우팅**: `go_router` 권장 (URL 동기화). `Navigator 1.0` 의 `MaterialApp.routes` 도 OK 지만 hash routing 주의
+- **자산**: `web/index.html`, `web/manifest.json`, `web/icons/` 관리. SEO 가 필요하면 `<meta>` 태그 명시
+- **CORS**: 백엔드 API 가 `localhost:포트` 에서 다른 origin 일 수 있으므로 CORS 설정 확인
+- **Eval 흐름**: Playwright 기반 `evaluator-functional` + `evaluator-visual` 이 정상 작동 (브라우저 E2E + 시각 검증)
+- 상세 → [Flutter Web Pattern](references/flutter-web-pattern.md)
+
+### `fe_target = mobile` (Android / iOS)
+
+- **빌드**: `flutter build apk` / `flutter build ios` / 개발: `flutter run -d <device>`
+- **HTML/JS 인터롭 금지**: `dart:html`, `package:web`, `universal_html` 직접 참조 → 빌드 실패
+- **플랫폼 채널**: 네이티브 기능 사용 시 `MethodChannel` 또는 검증된 plugin 사용
+- **권한**: `AndroidManifest.xml` / `Info.plist` 에 권한 명시
+- **Eval 흐름**: 정적 분석 기반 `evaluator-functional-flutter` 사용 (Playwright 불가)
+
+### `fe_target = desktop` (macOS / Windows / Linux)
+
+- **빌드**: `flutter build macos` / `flutter build windows` / `flutter build linux`
+- **HTML/JS 인터롭 금지**: 모바일과 동일
+- **윈도우 관리**: `window_manager` 등 플러그인으로 윈도우 크기/위치 제어
+- **Eval 흐름**: 정적 분석 기반 `evaluator-functional-flutter` 사용
 
 ## 핵심 규칙
 

package/skills/generator-frontend-flutter/references/anti-patterns.md

@@ -33,26 +33,49 @@ docmeta:
 
 각 항목은 **패턴 → 이유 → 대체 방법** 형태.
 
-## 1. 웹 전용 API 직접 참조
+## 1. 웹 전용 API 직접 참조 (fe_target 별 차이)
 
-### 금지
+### `fe_target = mobile` 또는 `desktop` — 금지
 ```dart
-import 'dart:html';
-import 'package:universal_html/html.dart';
+import 'dart:html';                              // ✗
+import 'package:universal_html/html.dart';       // ✗
+import 'package:web/web.dart';                   // ✗ (가드 없으면)
 ```
 
 ### 이유
-Flutter 앱은 크로스 플랫폼 — 모바일 빌드에서 `dart:html` 참조는 즉시 빌드 실패한다.
-Web 빌드 전용 코드가 필요하면 조건부 import 패턴을 사용한다.
+Flutter 모바일/데스크톱 빌드에서 `dart:html` 참조는 즉시 빌드 실패한다.
+가드 없이 import 하면 cross-platform 코드가 깨진다.
 
 ### 대체
-`package:web` 또는 `kIsWeb` 분기로 플랫폼 체크 후 조건부 import.
+- `kIsWeb` 분기로 플랫폼 체크 후 조건부 import
+- `if (kIsWeb) { ... }` 가드 안에서만 web API 사용
+- 또는 conditional import (`stub.dart` / `web.dart` / `io.dart`)
+
+### `fe_target = web` — 허용 (단, 권장 패턴 준수)
+```dart
+import 'package:web/web.dart' as web;            // ✓ 권장 (modern)
+import 'dart:js_interop';                        // ✓ JS interop
+import 'dart:html';                              // ✓ (legacy, 신규 코드는 package:web 권장)
+```
+
+### Web 권장 패턴
+- 새 코드는 `package:web` + `dart:js_interop` 사용 (Flutter 3.7+ 에서 stable)
+- `dart:html` 은 legacy — 마이그레이션 대상이지만 즉시 금지는 아님
+- 가능하면 web 전용 코드를 별도 파일로 분리하고 conditional import:
+  ```dart
+  // _web_helper.dart 또는 conditional import
+  import 'platform_helper.dart'
+    if (dart.library.html) 'platform_helper_web.dart'
+    if (dart.library.io) 'platform_helper_io.dart';
+  ```
 
 ### 검증
 ```bash
-grep -rn "dart:html\|universal_html" lib/ integrated_data_layer/lib/
+# fe_target = mobile/desktop: 0개여야 함
+grep -rn "dart:html\|universal_html\|package:web" lib/ integrated_data_layer/lib/
+
+# fe_target = web: 매치 OK, 단 'kIsWeb' 가드 또는 conditional import 와 함께 쓰는지 인접 라인 확인
 ```
-결과 0개여야 함.
 
 ---
 
@@ -263,11 +286,20 @@ grep -rEn "(api[_-]?key|secret|token)\s*=\s*['\"][A-Za-z0-9]{16,}['\"]" lib/ int
 
 ## 셀프 체크 스크립트
 
-Generator는 handoff 전 다음 명령을 모두 실행하고 결과를 sprint-contract.md에 기록한다:
+Generator는 handoff 전 다음 명령을 모두 실행하고 결과를 sprint-contract.md에 기록한다.
+**`fe_target` 에 따라 1번 룰의 적용 여부가 달라진다.**
 
 ```bash
-# 1. 웹 API 직접 참조
-grep -rn "dart:html\|universal_html" lib/ integrated_data_layer/lib/ || echo "OK"
+# fe_target 읽기
+FE_TARGET=$(jq -r '.fe_target // "web"' .harness/actions/pipeline.json 2>/dev/null || echo "web")
+
+# 1. 웹 API 직접 참조 — fe_target=web 이 아닐 때만 검사
+if [ "$FE_TARGET" != "web" ]; then
+  grep -rn "dart:html\|universal_html\|package:web" lib/ integrated_data_layer/lib/ || echo "OK (FL-01 mobile/desktop)"
+else
+  # web 타겟: 가드 없는 사용만 경고 (수동 검토)
+  grep -rn "dart:html\|package:web" lib/ | grep -v "kIsWeb\|conditional import" || echo "OK (FL-01 web — manual review)"
+fi
 
 # 2. print 남발
 grep -rn "^\s*print(" lib/ integrated_data_layer/lib/ || echo "OK"

package/skills/generator-frontend-flutter/references/flutter-web-pattern.md

@@ -0,0 +1,273 @@
+---
+docmeta:
+  id: flutter-web-pattern
+  title: Flutter Web 패턴 — fe_target=web 전용
+  type: output
+  createdAt: 2026-04-09T00:00:00Z
+  updatedAt: 2026-04-09T00:00:00Z
+  source:
+    producer: agent
+    skillId: harness-generator-frontend-flutter
+  inputs:
+    - documentId: harness-generator-frontend-flutter-skill
+      uri: ../SKILL.md
+      relation: output-from
+      sections:
+        - sourceRange:
+            startLine: 56
+            endLine: 90
+          targetRange:
+            startLine: 21
+            endLine: 240
+    - documentId: flutter-anti-patterns
+      uri: ./anti-patterns.md
+      relation: output-from
+      sections:
+        - sourceRange:
+            startLine: 22
+            endLine: 75
+          targetRange:
+            startLine: 90
+            endLine: 165
+  tags:
+    - flutter
+    - flutter-web
+    - dart-web
+    - go-router
+---
+
+# Flutter Web 패턴 (`fe_target = web` 전용)
+
+`pipeline.json.fe_target == "web"` 일 때만 적용. Mobile/Desktop 타겟에서는 이 문서의 규칙을 무시한다.
+
+## 1. 프로젝트 활성화
+
+기존 Flutter 프로젝트에 Web 타겟이 없으면:
+
+```bash
+flutter config --enable-web
+flutter create --platforms=web .
+```
+
+`web/index.html`, `web/manifest.json`, `web/favicon.png`, `web/icons/` 가 생성된다.
+
+## 2. 빌드 및 개발 서버
+
+| 명령 | 용도 |
+|------|------|
+| `flutter run -d chrome` | 개발 서버 (HMR 포함) |
+| `flutter run -d chrome --web-port 8080` | 포트 고정 |
+| `flutter build web --release` | 프로덕션 빌드 (`build/web/`) |
+| `flutter build web --release --web-renderer canvaskit` | CanvasKit 렌더러 (성능 우선) |
+| `flutter build web --release --web-renderer html` | HTML 렌더러 (호환성 우선, 작은 번들) |
+
+> **렌더러 선택**: 모바일 사파리 호환성이 중요하면 `html`, 데스크톱/Chrome 중심이면 `canvaskit` (또는 auto).
+
+## 3. 라우팅 — `go_router` 권장
+
+URL 동기화 + 브라우저 history 지원을 위해 `go_router` 사용.
+
+```yaml
+# pubspec.yaml
+dependencies:
+  go_router: ^14.0.0
+```
+
+```dart
+// lib/router/app_router.dart
+import 'package:go_router/go_router.dart';
+
+final pAppRouterProvider = Provider<GoRouter>((ref) {
+  return GoRouter(
+    initialLocation: '/',
+    routes: [
+      GoRoute(path: '/', builder: (ctx, state) => const HomePage()),
+      GoRoute(path: '/login', builder: (ctx, state) => const LoginPage()),
+      GoRoute(
+        path: '/items/:id',
+        builder: (ctx, state) => ItemPage(id: state.pathParameters['id']!),
+      ),
+    ],
+  );
+});
+```
+
+```dart
+// main.dart
+class App extends ConsumerWidget {
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final router = ref.watch(pAppRouterProvider);
+    return MaterialApp.router(
+      routerConfig: router,
+      // ...
+    );
+  }
+}
+```
+
+**Hash routing vs Path routing**:
+- 기본은 hash routing (`/#/login`)
+- Path routing 으로 바꾸려면 `web/index.html` 의 `<base href="/">` 설정 + 서버 fallback (모든 경로 → `index.html`)
+
+## 4. JS Interop (필요할 때만)
+
+크로스플랫폼 코드를 우선하되, Web 전용 API 가 필요하면 `package:web` + `dart:js_interop` 사용.
+
+```dart
+import 'package:web/web.dart' as web;
+import 'dart:js_interop';
+
+void copyToClipboard(String text) {
+  web.window.navigator.clipboard.writeText(text.toJS);
+}
+
+String getUserAgent() => web.window.navigator.userAgent;
+```
+
+**Conditional import 패턴** (cross-platform 코드를 web/io 로 분기):
+
+```dart
+// platform_helper.dart (interface)
+abstract class PlatformHelper {
+  String get platformName;
+}
+
+PlatformHelper getPlatformHelper() => throw UnimplementedError();
+```
+
+```dart
+// platform_helper_web.dart
+import 'package:web/web.dart' as web;
+import 'platform_helper.dart';
+
+class WebPlatformHelper implements PlatformHelper {
+  @override
+  String get platformName => 'web (${web.window.navigator.userAgent})';
+}
+
+PlatformHelper getPlatformHelper() => WebPlatformHelper();
+```
+
+```dart
+// platform_helper_io.dart
+import 'dart:io';
+import 'platform_helper.dart';
+
+class IoPlatformHelper implements PlatformHelper {
+  @override
+  String get platformName => 'io (${Platform.operatingSystem})';
+}
+
+PlatformHelper getPlatformHelper() => IoPlatformHelper();
+```
+
+```dart
+// 사용처
+import 'platform_helper.dart'
+  if (dart.library.html) 'platform_helper_web.dart'
+  if (dart.library.io) 'platform_helper_io.dart';
+
+final helper = getPlatformHelper();
+print(helper.platformName);
+```
+
+## 5. CORS 와 백엔드 연동
+
+Flutter Web 은 브라우저에서 실행되므로 백엔드 API 호출 시 **CORS** 가 적용된다.
+
+- 개발 단계: 백엔드 Gateway 의 `Access-Control-Allow-Origin` 에 `http://localhost:8080` (또는 `*`) 추가
+- 프로덕션: 동일 origin 또는 명시적 CORS 화이트리스트
+- API 키/인증 토큰은 **HttpOnly cookie** 또는 메모리 보관 (localStorage 는 XSS 위험)
+
+`Dio` 인터셉터로 CSRF 토큰 등을 헤더에 추가:
+
+```dart
+final dio = Dio(BaseOptions(
+  baseUrl: 'https://api.example.com',
+  headers: {'Content-Type': 'application/json'},
+));
+
+dio.interceptors.add(InterceptorsWrapper(
+  onRequest: (options, handler) {
+    final token = ref.read(pAuthProvider).accessToken;
+    if (token != null) {
+      options.headers['Authorization'] = 'Bearer $token';
+    }
+    return handler.next(options);
+  },
+));
+```
+
+## 6. SEO / Meta Tags
+
+`web/index.html` 의 `<head>` 에 SEO 메타 태그 추가:
+
+```html
+<meta name="description" content="Suprema CLUe — Smart Access Control">
+<meta property="og:title" content="CLUe">
+<meta property="og:description" content="...">
+<meta property="og:image" content="/icons/og-image.png">
+<link rel="canonical" href="https://app.example.com">
+```
+
+> SPA 의 SEO 한계: Flutter Web 은 client-side rendering 이므로 검색엔진이 동적 콘텐츠를 인덱싱하지 못할 수 있다. SSR 이 필요하면 Next.js + REST API 패턴을 고려.
+
+## 7. 자산 최적화
+
+- 이미지: `assets/images/` 에 두고 `pubspec.yaml` 의 `flutter.assets` 에 등록
+- 폰트: `web/fonts/` 또는 `assets/fonts/` + `pubspec.yaml` 의 `flutter.fonts`
+- 큰 이미지: webp 사용 권장 (`flutter_image_compress` 또는 사전 변환)
+- Tree-shaking: `flutter build web --tree-shake-icons` 로 사용하지 않는 Material 아이콘 제거
+
+## 8. PWA (Progressive Web App)
+
+`flutter create --platforms=web` 시 자동 생성되는 `web/manifest.json` 을 채워서 PWA 로 동작:
+
+```json
+{
+  "name": "CLUe",
+  "short_name": "CLUe",
+  "start_url": "/",
+  "display": "standalone",
+  "background_color": "#FFFFFF",
+  "theme_color": "#6682FF",
+  "icons": [
+    { "src": "icons/Icon-192.png", "sizes": "192x192", "type": "image/png" },
+    { "src": "icons/Icon-512.png", "sizes": "512x512", "type": "image/png" }
+  ]
+}
+```
+
+Service worker 는 `flutter build web` 시 자동 생성된다 (`flutter_service_worker.js`).
+
+## 9. 디버깅 — Chrome DevTools
+
+- `flutter run -d chrome` 후 Chrome 자체 DevTools 열기 (F12)
+- Console 에서 `print()` 출력 확인 가능 (단, 프로덕션 빌드에서는 `print` 금지)
+- Source map 활성화: `--web-renderer html --source-maps` (디버그 빌드 기본)
+- Network 탭에서 API 호출 직접 검사 가능 → Playwright 기반 `evaluator-functional` 도 동일하게 동작
+
+## 10. Eval 인터페이스
+
+`fe_target = web` 인 경우 `harness-next.sh` 가 다음과 같이 자동 라우팅:
+
+```
+generator-frontend-flutter (Self-Verification: flutter analyze + flutter test)
+  → evaluator-functional (Playwright MCP — http://localhost:포트 E2E)
+  → evaluator-visual (Playwright MCP — 스크린샷 + 반응형 + 접근성)
+```
+
+**Generator 의 Self-Verification 단계에서 `flutter build web --release` 가 성공하는지 확인** 후 handoff.
+
+## 11. 호스팅 (참고)
+
+| 호스팅 | 빌드 산출물 |
+|--------|------------|
+| Vercel | `build/web/` 디렉토리를 정적 호스팅 |
+| Netlify | 동일 |
+| Firebase Hosting | `firebase deploy --only hosting` (firebase.json 의 public 을 `build/web` 으로) |
+| GitHub Pages | `build/web/` 을 gh-pages 브랜치에 푸시 |
+| 자체 서버 | nginx 로 정적 파일 서빙 + SPA fallback (`try_files $uri /index.html`) |
+
+호스팅 결정은 Planner / 사용자가 함. Generator 는 빌드 산출물만 보장.

package/skills/planner/references/fe-stack-detection.md

@@ -76,40 +76,87 @@ Planner는 Sprint 1 착수 전 반드시 `fe_stack`을 확정하고 `pipeline.js
 
 혼재 프로젝트(Web + Flutter mobile)라면 사용자에게 **현 스프린트의 타깃**을 묻는다 — 파이프라인은 한 번에 하나의 `fe_stack`만 취급한다.
 
+## 2.5 fe_target 확정 (Flutter 전용)
+
+`fe_stack == "flutter"` 인 경우, **반드시** `fe_target` 도 함께 확정해야 한다 (`web` | `mobile` | `desktop`).
+이는 Flutter Web vs Mobile/Desktop 에서 사용 가능한 API, 빌드 명령, evaluator 가 달라지기 때문이다.
+
+### 자동 감지 (scan-result.json 의 `tech_stack.fe_target`)
+
+| 시그널 | fe_target |
+|--------|-----------|
+| `<flutter_root>/web/index.html` 존재 | `web` |
+| `<flutter_root>/android/` 또는 `ios/` 존재, web/ 없음 | `mobile` |
+| `<flutter_root>/macos/`, `windows/`, `linux/` 존재 (mobile/web 없음) | `desktop` |
+| 없음 | `unknown` |
+
+### 사용자 질문 (불명확하거나 multi-target)
+
+```
+Flutter 프로젝트의 타깃을 확인합니다:
+
+(A) Web — 브라우저 (Chrome/Safari/Firefox), 컴파일 결과는 HTML+JS+CSS
+(B) Mobile — Android / iOS 네이티브 빌드
+(C) Desktop — macOS / Windows / Linux 네이티브 빌드
+
+감지된 시그널:
+- web/index.html: [있음/없음]
+- android|ios/: [있음/없음]
+- macos|windows|linux/: [있음/없음]
+
+이번 스프린트의 타깃은? (A/B/C)
+```
+
+### fe_target → Eval 흐름
+
+| fe_target | Generator | Eval-Functional | Eval-Visual |
+|-----------|-----------|----------------|-------------|
+| `web` | `generator-frontend-flutter` | `evaluator-functional` (Playwright!) | `evaluator-visual` (Playwright!) |
+| `mobile` | `generator-frontend-flutter` | `evaluator-functional-flutter` (정적 분석) | SKIP |
+| `desktop` | `generator-frontend-flutter` | `evaluator-functional-flutter` (정적 분석) | SKIP |
+
+**핵심**: Flutter Web 의 빌드 결과물(HTML/JS/CSS)은 일반 웹앱과 동일하므로 Playwright 기반
+React 경로의 evaluator 를 그대로 재사용한다. Generator-Frontend-Flutter 의 Self-Verification
+단계에서 `flutter analyze`/`flutter test`/`flutter build web` 정적 검증이 이미 통과한 상태로 handoff 된다.
+
 ## 3. pipeline.json 갱신
 
-`fe_stack` 확정 후 `pipeline.json`에 반드시 추가:
+`fe_stack` + `fe_target` 확정 후 `pipeline.json`에 반드시 추가:
 
 ```json
 {
   "pipeline": "FULLSTACK",
   "planner_mode": "full",
   "fe_stack": "flutter",
+  "fe_target": "web",
   "agents_active": [
     "planner",
     "generator-backend",
     "generator-frontend-flutter",
-    "evaluator-functional-flutter"
+    "evaluator-functional",
+    "evaluator-visual"
   ],
   "agents_skipped": [
     "generator-frontend",
-    "evaluator-functional",
-    "evaluator-visual"
+    "evaluator-functional-flutter"
   ],
-  "evaluator_mode": "flutter-native",
-  "notes": "Flutter 앱 — Playwright 대신 flutter analyze/test + 정적 anti-pattern 검증"
+  "evaluator_mode": "playwright-web",
+  "notes": "Flutter Web — 컴파일 결과가 HTML+JS+CSS 이므로 React 경로의 Playwright evaluator 사용. Generator 의 Self-Verification 에서 flutter analyze/test 통과 전제."
 }
 ```
 
-### fe_stack → 파이프라인 매핑
-
-| pipeline | fe_stack | agents_active 예시 |
-|----------|----------|-------------------|
-| FULLSTACK | react | planner, generator-backend, generator-frontend, evaluator-functional, evaluator-visual |
-| FULLSTACK | flutter | planner, generator-backend, generator-frontend-flutter, evaluator-functional-flutter |
-| FE-ONLY | react | planner, generator-frontend, evaluator-functional, evaluator-visual |
-| FE-ONLY | flutter | planner, generator-frontend-flutter, evaluator-functional-flutter |
-| BE-ONLY | (무관) | planner, generator-backend, evaluator-functional |
+### fe_stack + fe_target → 파이프라인 매핑
+
+| pipeline | fe_stack | fe_target | agents_active 예시 |
+|----------|----------|-----------|-------------------|
+| FULLSTACK | react | (n/a) | planner, generator-backend, generator-frontend, evaluator-functional, evaluator-visual |
+| FULLSTACK | flutter | **web** | planner, generator-backend, generator-frontend-flutter, evaluator-functional, evaluator-visual |
+| FULLSTACK | flutter | mobile | planner, generator-backend, generator-frontend-flutter, evaluator-functional-flutter |
+| FULLSTACK | flutter | desktop | planner, generator-backend, generator-frontend-flutter, evaluator-functional-flutter |
+| FE-ONLY | react | (n/a) | planner, generator-frontend, evaluator-functional, evaluator-visual |
+| FE-ONLY | flutter | **web** | planner, generator-frontend-flutter, evaluator-functional, evaluator-visual |
+| FE-ONLY | flutter | mobile | planner, generator-frontend-flutter, evaluator-functional-flutter |
+| BE-ONLY | (무관) | (n/a) | planner, generator-backend, evaluator-functional |
 
 ## 4. Flutter 선택 시 추가 작업