@walwal-harness/cli 2.4.0 → 3.2.0

package/scripts/harness-session-start.sh

@@ -1,31 +1,34 @@
 #!/bin/bash
-# harness-session-start.sh — SessionStart 훅
-# Claude Code 세션 시작 시 자동 실행되어 현재 하네스 상태를 출력한다.
-# .claude/settings.json의 SessionStart 훅으로 등록된다.
+# harness-session-start.sh — SessionStart 훅 (compact)
+# statusline이 상시 상태를 표시하므로, 여기서는 핵심 안내만 출력.
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 LIB="$SCRIPT_DIR/lib/harness-render-progress.sh"
 
-# lib이 없으면 silent exit (훅이므로 에러 출력하지 않음)
 if [ ! -f "$LIB" ]; then exit 0; fi
 source "$LIB"
-
-# jq 없으면 silent exit
 command -v jq &>/dev/null || exit 0
 
-# .harness/ 찾기
 PROJECT_ROOT="$(resolve_harness_root "." 2>/dev/null)" || exit 0
-
 PROGRESS="$PROJECT_ROOT/.harness/progress.json"
 [ -f "$PROGRESS" ] || exit 0
 
-# init 상태면 간단 안내만
 sprint_status=$(jq -r '.sprint.status // "init"' "$PROGRESS" 2>/dev/null)
+current_agent=$(jq -r '.current_agent // "none"' "$PROGRESS" 2>/dev/null)
+next_agent=$(jq -r '.next_agent // "none"' "$PROGRESS" 2>/dev/null)
+agent_status=$(jq -r '.agent_status // "pending"' "$PROGRESS" 2>/dev/null)
+
+# init 상태: 간단 안내
 if [ "$sprint_status" = "init" ]; then
   echo "# Harness ready — say \"하네스 엔지니어링 시작\" or /harness-dispatcher"
   exit 0
 fi
 
-# Feature-level 프로그래스 출력
-render_progress "$PROJECT_ROOT"
-render_agent_bar "$PROJECT_ROOT"
+# 활성 세션: 다음 액션만 안내 (상세 프로그래스는 statusline에서 상시 표시)
+if [ "$agent_status" = "blocked" ]; then
+  echo "# Harness BLOCKED — user intervention required. Run: bash scripts/harness-next.sh"
+elif [ "$next_agent" != "none" ] && [ "$next_agent" != "null" ]; then
+  echo "# Harness: next → /harness-${next_agent}"
+elif [ "$current_agent" != "none" ] && [ "$current_agent" != "null" ]; then
+  echo "# Harness: ${current_agent} [${agent_status}]"
+fi

package/scripts/harness-statusline.sh

@@ -0,0 +1,93 @@
+#!/bin/bash
+# harness-statusline.sh — Claude Code statusline hook
+# 터미널 하단에 항상 고정되는 1줄 compact 상태 표시.
+# stdin: Claude Code JSON payload (model, context_window, cost 등)
+# stdout: 상태 문자열 (Claude Code가 터미널 하단에 렌더링)
+
+# Read Claude Code session data from stdin
+input=$(cat)
+
+# Extract Claude Code built-in data
+context_pct=$(echo "$input" | jq -r '.context_window.used_percentage // 0' 2>/dev/null | cut -d. -f1)
+cost=$(echo "$input" | jq -r '.cost.total_cost_usd // 0' 2>/dev/null)
+
+# Resolve project root (walk up from cwd)
+CWD=$(echo "$input" | jq -r '.workspace.current_dir // empty' 2>/dev/null)
+if [ -z "$CWD" ]; then CWD="$PWD"; fi
+
+PROJECT_ROOT="$CWD"
+while [ "$PROJECT_ROOT" != "/" ]; do
+  if [ -d "$PROJECT_ROOT/.harness" ]; then break; fi
+  PROJECT_ROOT="$(dirname "$PROJECT_ROOT")"
+done
+
+PROGRESS="$PROJECT_ROOT/.harness/progress.json"
+FEATURE_LIST="$PROJECT_ROOT/.harness/actions/feature-list.json"
+PIPELINE_JSON="$PROJECT_ROOT/.harness/actions/pipeline.json"
+
+# No harness → minimal status
+if [ ! -f "$PROGRESS" ]; then
+  echo "harness: not initialized | ctx ${context_pct}%"
+  exit 0
+fi
+
+# Read harness state
+sprint_num=$(jq -r '.sprint.number // 0' "$PROGRESS" 2>/dev/null)
+sprint_status=$(jq -r '.sprint.status // "init"' "$PROGRESS" 2>/dev/null)
+pipeline=$(jq -r '.pipeline // "?"' "$PROGRESS" 2>/dev/null)
+current_agent=$(jq -r '.current_agent // "none"' "$PROGRESS" 2>/dev/null)
+agent_status=$(jq -r '.agent_status // "pending"' "$PROGRESS" 2>/dev/null)
+next_agent=$(jq -r '.next_agent // "none"' "$PROGRESS" 2>/dev/null)
+retry_count=$(jq -r '.sprint.retry_count // 0' "$PROGRESS" 2>/dev/null)
+
+# Pipeline short name
+case "$pipeline" in
+  FULLSTACK) pl="FULL" ;;
+  FE-ONLY)   pl="FE" ;;
+  BE-ONLY)   pl="BE" ;;
+  null|"?")  pl="?" ;;
+  *)         pl="$pipeline" ;;
+esac
+
+# Agent short name (strip harness prefix)
+agent_short="${current_agent#generator-}"
+agent_short="${agent_short#evaluator-}"
+if [ "$current_agent" = "none" ] || [ "$current_agent" = "null" ]; then
+  agent_short="$next_agent"
+  if [ "$agent_short" = "none" ] || [ "$agent_short" = "null" ]; then
+    agent_short="idle"
+  fi
+fi
+
+# Feature progress
+total_features=0
+completed_features=0
+if [ -f "$FEATURE_LIST" ]; then
+  total_features=$(jq '.features | length' "$FEATURE_LIST" 2>/dev/null || echo 0)
+  completed_features=$(jq '[.features[]? | select(
+    (.passes // []) | (
+      (map(select(. == "evaluator-functional")) | length > 0) and
+      (map(select(. == "evaluator-visual")) | length > 0)
+    )
+  )] | length' "$FEATURE_LIST" 2>/dev/null || echo 0)
+fi
+
+# Status indicator
+status_icon=""
+case "$agent_status" in
+  running)   status_icon=">" ;;
+  completed) status_icon="v" ;;
+  failed)    status_icon="x" ;;
+  blocked)   status_icon="!" ;;
+  *)         status_icon="-" ;;
+esac
+
+# Retry indicator
+retry_str=""
+if [ "$retry_count" -gt 0 ]; then
+  retry_str=" R${retry_count}"
+fi
+
+# Build compact status line
+# Format: [S1] FULL | >backend | 2/5 feat | R0 | ctx 45% | $1.23
+echo "[S${sprint_num}] ${pl} | ${status_icon}${agent_short}${retry_str} | ${completed_features}/${total_features} feat | ctx ${context_pct}% | \$${cost}"

package/scripts/harness-user-prompt-submit.sh

@@ -1,55 +1,31 @@
 #!/bin/bash
-# harness-user-prompt-submit.sh
-# ─────────────────────────────────────────
-# Claude Code UserPromptSubmit hook
-# 모든 사용자 프롬프트를 harness-dispatcher 로 라우팅하도록 Claude 에게
-# 지시하는 컨텍스트를 stdout 에 주입한다.
-#
-# 활성 조건:
-#   1) 현재 cwd 에 .harness/config.json 존재
-#   2) .harness/config.json 의 behavior.auto_route_dispatcher != false
-#
-# 비활성 상황에서는 아무것도 출력하지 않고 exit 0 (pass-through).
-# ─────────────────────────────────────────
+# harness-user-prompt-submit.sh — UserPromptSubmit hook (compact v3.2)
+# 핵심 상태 + 라우팅 지시만 주입. 장황한 설명 제거.
 set -e
 
-# stdin 의 JSON payload 읽기 (Claude Code 가 {prompt, cwd, session_id, ...} 전달)
 INPUT=$(cat)
-
-# cwd 추출 (payload 에 없으면 PWD fallback)
 CWD=$(echo "$INPUT" | jq -r '.cwd // empty' 2>/dev/null || true)
-if [ -z "$CWD" ]; then
-  CWD="$PWD"
-fi
+if [ -z "$CWD" ]; then CWD="$PWD"; fi
 
 # 조건 1: 하네스 초기화 확인
-if [ ! -f "$CWD/.harness/config.json" ]; then
-  exit 0
-fi
+if [ ! -f "$CWD/.harness/config.json" ]; then exit 0; fi
 
-# 조건 2: opt-out 플래그 확인 (기본값 true)
+# 조건 2: opt-out 플래그 확인
 AUTO_ROUTE="true"
 if command -v jq >/dev/null 2>&1; then
   AUTO_ROUTE=$(jq -r '.behavior.auto_route_dispatcher // true' "$CWD/.harness/config.json" 2>/dev/null || echo "true")
 fi
-if [ "$AUTO_ROUTE" != "true" ]; then
-  exit 0
-fi
+if [ "$AUTO_ROUTE" != "true" ]; then exit 0; fi
 
-# 프롬프트 내용 추출 (opt-out 문구 감지용)
+# 사용자 skip 감지
 PROMPT=$(echo "$INPUT" | jq -r '.prompt // empty' 2>/dev/null || true)
-# 사용자가 명시적으로 건너뛰기 요청하면 pass-through
 if echo "$PROMPT" | grep -qiE "harness\s*(skip|off|bypass|없이)|without\s*harness|just\s*(answer|chat|reply)"; then
   exit 0
 fi
 
 # 현재 세션 상태 읽기
-PIPELINE="none"
-CURRENT_AGENT="none"
-NEXT_AGENT="none"
-SPRINT_NUM="0"
-SPRINT_STATUS="init"
-FE_STACK="react"
+PIPELINE="none"; CURRENT_AGENT="none"; NEXT_AGENT="none"
+SPRINT_NUM="0"; SPRINT_STATUS="init"; AGENT_STATUS="pending"
 
 if [ -f "$CWD/.harness/progress.json" ] && command -v jq >/dev/null 2>&1; then
   PIPELINE=$(jq -r '.pipeline // "none"' "$CWD/.harness/progress.json" 2>/dev/null || echo "none")
@@ -57,50 +33,33 @@ if [ -f "$CWD/.harness/progress.json" ] && command -v jq >/dev/null 2>&1; then
   NEXT_AGENT=$(jq -r '.next_agent // "none"' "$CWD/.harness/progress.json" 2>/dev/null || echo "none")
   SPRINT_NUM=$(jq -r '.sprint.number // 0' "$CWD/.harness/progress.json" 2>/dev/null || echo "0")
   SPRINT_STATUS=$(jq -r '.sprint.status // "init"' "$CWD/.harness/progress.json" 2>/dev/null || echo "init")
+  AGENT_STATUS=$(jq -r '.agent_status // "pending"' "$CWD/.harness/progress.json" 2>/dev/null || echo "pending")
 fi
 
-if [ -f "$CWD/.harness/actions/pipeline.json" ] && command -v jq >/dev/null 2>&1; then
-  FE_STACK=$(jq -r '.fe_stack // "react"' "$CWD/.harness/actions/pipeline.json" 2>/dev/null || echo "react")
+# ── 컨텍스트 분리 가드레일 ──
+# 현재 에이전트가 활성인데 다른 에이전트 스킬을 호출하려는 경우 경고
+CONTEXT_WARNING=""
+if [ "$CURRENT_AGENT" != "none" ] && [ "$CURRENT_AGENT" != "null" ] && [ "$AGENT_STATUS" = "running" ]; then
+  # 프롬프트에서 /harness-* 패턴 추출
+  REQUESTED_SKILL=$(echo "$PROMPT" | grep -oE '/harness-[a-z-]+' | head -1 | sed 's|/harness-||')
+  if [ -n "$REQUESTED_SKILL" ] && [ "$REQUESTED_SKILL" != "$CURRENT_AGENT" ]; then
+    CONTEXT_WARNING="
+## !! Context Isolation Warning !!
+current_agent=${CURRENT_AGENT} (running) 인데 /harness-${REQUESTED_SKILL} 호출 감지.
+한 세션에서 다른 에이전트를 실행하면 컨텍스트가 오염됩니다.
+현재 에이전트를 먼저 완료(completed)하거나, 새 세션을 시작하세요."
+  fi
 fi
 
-# ─────────────────────────────────────────
-# Context 주입 (stdout → Claude 컨텍스트)
-# ─────────────────────────────────────────
+# ── Compact context 주입 ──
 cat <<EOF
-[walwal-harness] Auto-routing is ACTIVE for this project.
-
-이 프로젝트는 walwal-harness 가 초기화되어 있으며, auto_route_dispatcher 플래그가
-켜져 있습니다. 사용자의 모든 프롬프트는 **harness-dispatcher** 스킬을 통해
-분류/라우팅된 뒤 처리되어야 합니다.
-
-## 분류 규칙 (Dispatcher Request Classification)
-- **기능 요청** (만들어줘, 추가, 고쳐줘, PRD, OpenAPI) → Pipeline Flow
-- **실수 지적** (아니, 잘못됐어, 그렇게 하면 안 돼, X로 해야지) → Gotcha Flow
-- **혼합** → Gotcha 먼저 기록 → Pipeline 이어서
-- **메타/인사/Claude 자체 질문** → 짧게 일반 응답 (dispatcher skip 허용)
-
-## 현재 harness 세션 상태
-- pipeline: $PIPELINE
-- current_agent: $CURRENT_AGENT
-- next_agent: $NEXT_AGENT
-- sprint: $SPRINT_NUM ($SPRINT_STATUS)
-- fe_stack: $FE_STACK
-
-## 지시
-1. 먼저 위 상태를 읽고, 사용자 메시지가 어떤 분류에 해당하는지 판단
-2. **pipeline 이 'none' 또는 dispatcher 미실행 상태**면 harness-dispatcher 스킬 호출
-3. **pipeline 이 이미 활성**이면:
-   - 실수 지적이면 → dispatcher 로 gotcha 기록
-   - 기능 연속 작업이면 → next_agent 또는 current_agent 의 컨텍스트로 계속
-4. 응답 전 반드시 \`.harness/progress.json\` 을 읽고 세션 경계 프로토콜 준수
-
-## 이 라우팅을 건너뛰려면
-- **단일 메시지**: 사용자가 "harness skip", "without harness", "harness 없이", "just answer" 등을 명시
-- **전역 비활성**: \`.harness/config.json\` 에서 \`behavior.auto_route_dispatcher = false\` 설정
-
-## 참고
-이 안내는 \`scripts/harness-user-prompt-submit.sh\` UserPromptSubmit 훅에 의해
-매 프롬프트마다 자동 주입됩니다. 중복 안내처럼 보여도 무시하지 말고 위 규칙을 따르세요.
+[harness] S${SPRINT_NUM} | ${PIPELINE} | agent=${CURRENT_AGENT} (${AGENT_STATUS}) | next=${NEXT_AGENT}
+${CONTEXT_WARNING}
+## Route
+- pipeline=none/dispatcher 미실행 → harness-dispatcher 스킬 호출
+- 기능 요청 → pipeline flow | 실수 지적 → gotcha flow | 메타 질문 → 짧게 응답 (skip)
+- 활성 pipeline → next_agent/current_agent 컨텍스트로 계속
+- skip: "harness skip", "just answer" 등 명시 시 단일 메시지 건너뜀
 EOF
 
 exit 0

package/scripts/lib/harness-guardrail.sh

@@ -0,0 +1,143 @@
+#!/bin/bash
+# harness-guardrail.sh — 런타임 파일 소유권 검증
+# 에이전트 전환 시 이전 에이전트가 권한 밖 파일을 수정했는지 git diff로 검증.
+#
+# 사용법: source lib/harness-guardrail.sh && verify_file_ownership "$PROJECT_ROOT"
+# 반환값: 0=통과, 1=위반 발견 (위반 목록을 stdout에 출력)
+
+# ─────────────────────────────────────────
+# Agent → 허용 경로 매핑
+# ─────────────────────────────────────────
+get_allowed_paths() {
+  local agent="$1"
+  case "$agent" in
+    planner)
+      echo "AGENTS.md"
+      echo ".harness/actions/"
+      echo ".harness/progress.json"
+      echo ".harness/progress.log"
+      ;;
+    generator-backend)
+      echo "apps/gateway/"
+      echo "apps/service-"
+      echo "libs/"
+      echo ".harness/actions/sprint-contract.md"
+      echo ".harness/actions/feature-list.json"
+      echo ".harness/progress.json"
+      echo "package.json"
+      echo "nest-cli.json"
+      echo "tsconfig"
+      echo "docker-compose"
+      ;;
+    generator-frontend|generator-frontend-flutter)
+      echo "apps/web/"
+      echo "apps/flutter/"
+      echo ".harness/actions/sprint-contract.md"
+      echo ".harness/actions/feature-list.json"
+      echo ".harness/progress.json"
+      echo "package.json"
+      echo "tsconfig"
+      echo "pubspec"
+      ;;
+    evaluator-functional|evaluator-functional-flutter)
+      echo ".harness/actions/evaluation-functional.md"
+      echo ".harness/progress.json"
+      echo "tests/"
+      echo "test/"
+      echo "e2e/"
+      echo "playwright"
+      ;;
+    evaluator-visual)
+      echo ".harness/actions/evaluation-visual.md"
+      echo ".harness/progress.json"
+      ;;
+    dispatcher)
+      echo ".harness/"
+      ;;
+    *)
+      echo "**"  # unknown agent — allow all (safe fallback)
+      ;;
+  esac
+}
+
+# ─────────────────────────────────────────
+# verify_file_ownership — git diff 기반 검증
+#
+# Args:
+#   $1 — project root
+#
+# Reads:
+#   .harness/progress.json (current_agent)
+#
+# Returns: 0=pass, 1=violation found
+# ─────────────────────────────────────────
+verify_file_ownership() {
+  local PROJECT_ROOT="$1"
+  local PROGRESS="$PROJECT_ROOT/.harness/progress.json"
+
+  if [ ! -f "$PROGRESS" ]; then return 0; fi
+
+  local agent
+  agent=$(jq -r '.current_agent // "null"' "$PROGRESS" 2>/dev/null)
+  if [ "$agent" = "null" ] || [ -z "$agent" ]; then return 0; fi
+
+  # git이 없으면 skip
+  if ! command -v git &>/dev/null; then return 0; fi
+
+  # 마지막 커밋 이후 변경된 파일 목록
+  local -a changed_files
+  mapfile -t changed_files < <(cd "$PROJECT_ROOT" && git diff --name-only HEAD 2>/dev/null)
+
+  # staged 파일도 포함
+  local -a staged_files
+  mapfile -t staged_files < <(cd "$PROJECT_ROOT" && git diff --name-only --cached 2>/dev/null)
+
+  # 합치기 (중복 제거)
+  local -a all_files
+  mapfile -t all_files < <(printf '%s\n' "${changed_files[@]}" "${staged_files[@]}" | sort -u | grep -v '^$')
+
+  if [ ${#all_files[@]} -eq 0 ]; then return 0; fi
+
+  # 허용 경로 목록
+  local -a allowed
+  mapfile -t allowed < <(get_allowed_paths "$agent")
+
+  # 위반 검사
+  local -a violations=()
+  for file in "${all_files[@]}"; do
+    local is_allowed=false
+    for pattern in "${allowed[@]}"; do
+      if [[ "$file" == $pattern* ]]; then
+        is_allowed=true
+        break
+      fi
+    done
+    if [ "$is_allowed" = false ]; then
+      violations+=("$file")
+    fi
+  done
+
+  if [ ${#violations[@]} -eq 0 ]; then
+    return 0
+  fi
+
+  # 위반 보고
+  echo ""
+  echo "  ── Guardrail Violation ────────────────"
+  echo "  Agent '$agent' modified files outside its allowed paths:"
+  echo ""
+  for v in "${violations[@]}"; do
+    echo "    ✗ $v"
+  done
+  echo ""
+  echo "  Allowed paths for $agent:"
+  for p in "${allowed[@]}"; do
+    echo "    ✓ $p*"
+  done
+  echo ""
+  echo "  Action: Review these changes before proceeding."
+  echo "  ─────────────────────────────────────────"
+  echo ""
+
+  return 1
+}

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` 사용
 
 ## 핵심 규칙