@walwal-harness/cli 5.0.9 → 5.2.0

package/commands/harness-team.md

@@ -210,6 +210,22 @@ Agent({
   prompt: "당신은 독립 Evaluator입니다. Generator가 작성한 코드를 AC 기준으로 냉정하게 평가합니다.
 Generator의 의도나 추론 과정은 알 수 없습니다. 오직 코드와 결과만 봅니다.
 
+## 실시간 로깅 (필수)
+
+평가 진행 상황을 실시간으로 기록합니다. **각 AC 검증마다 반드시 logev를 호출**하세요.
+
+```bash
+HARNESS_ROOT=$(git worktree list | head -1 | awk '{print $1}')
+LOG=\"$HARNESS_ROOT/.harness/progress.log\"
+logev() { echo \"$(date +'%Y-%m-%d %H:%M') | team-{N} | $1 | $2\" >> \"$LOG\"; }
+```
+
+**로깅 시점:**
+1. 평가 시작 즉시: `logev eval-start \"{FEATURE_ID} evaluating — {AC수} ACs\"`
+2. 각 AC 검증 후: `logev eval-check \"{FEATURE_ID} AC-{N}: [PASS/FAIL] {근거 요약}\"`
+3. tsc/eslint 검증 후: `logev eval-check \"{FEATURE_ID} gate: tsc {OK/FAIL}, eslint {OK/FAIL}\"`
+4. 최종 판정: `logev eval-done \"{FEATURE_ID} VERDICT={PASS/FAIL} SCORE={X.XX}/3.00\"`
+
 ## 평가 대상
 - Feature ID: {FEATURE_ID}
 - AC: jq '.features[] | select(.id == \"{FEATURE_ID}\").acceptance_criteria' .harness/actions/feature-list.json

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@walwal-harness/cli",
-  "version": "5.0.9",
+  "version": "5.2.0",
   "description": "Production harness for AI agent engineering — Solo/Team mode, Planner, Generator(BE/FE), Evaluator(Func/Visual), optional Brainstormer. Supports React, Next.js, and Flutter FE stacks.",
   "bin": {
     "walwal-harness": "bin/init.js"

package/scripts/harness-dashboard.sh

@@ -40,7 +40,7 @@ strip_ansi() {
 }
 
 get_term_width() {
-  tput cols 2>/dev/null || echo 80
+  echo "${_COLS:-$(tput cols 2>/dev/null || echo 80)}"
 }
 
 get_mode() {
@@ -150,14 +150,28 @@ render_solo_prompt_history() {
       local short_ts icon color
       short_ts=$(echo "$ts" | sed 's/^[0-9]*-//')
 
-      case "$agent" in
-        dispatcher*)  icon="▸" ; color="$MAGENTA" ;;
-        planner*)     icon="□" ; color="$YELLOW" ;;
-        generator*)   icon="▶" ; color="$GREEN" ;;
-        eval*)        icon="✦" ; color="$RED" ;;
-        team-*)       icon="◆" ; color="$CYAN" ;;
-        user*)        icon="★" ; color="$BOLD" ;;
-        *)            icon="·" ; color="$DIM" ;;
+      # action 기반으로 먼저 분류 (team 모드에서 agent=team-N이므로)
+      case "$action" in
+        eval-start|eval-check|eval-done|eval)
+          icon="✦" ; color="$MAGENTA" ;;
+        gen-start|gen-read|gen-write|gen-test|gen-done|gen)
+          icon="▶" ; color="$GREEN" ;;
+        result|pass)
+          icon="✓" ; color="$GREEN" ;;
+        fail)
+          icon="✗" ; color="$RED" ;;
+        *)
+          # fallback: agent 기반
+          case "$agent" in
+            dispatcher*)  icon="▸" ; color="$MAGENTA" ;;
+            planner*)     icon="□" ; color="$YELLOW" ;;
+            generator*)   icon="▶" ; color="$GREEN" ;;
+            eval*)        icon="✦" ; color="$MAGENTA" ;;
+            team-*)       icon="◆" ; color="$CYAN" ;;
+            user*)        icon="★" ; color="$BOLD" ;;
+            *)            icon="·" ; color="$DIM" ;;
+          esac
+          ;;
       esac
 
       if [ ${#detail} -gt 40 ]; then detail="${detail:0:38}.."; fi
@@ -331,9 +345,10 @@ render_archive_prompts() {
   total_prompts=$(echo "$all_prompts" | wc -l | tr -d ' ')
 
   # 마지막 프롬프트를 제외한 모든 프롬프트 = archived (처리 완료)
+  # newest first (tac), 전체 출력 (제한 없음)
   local archived
   if [ "$total_prompts" -le 1 ]; then return; fi
-  archived=$(echo "$all_prompts" | head -n $((total_prompts - 1)) | tail -8)
+  archived=$(echo "$all_prompts" | head -n $((total_prompts - 1)) | tac)
 
   echo ""
   echo -e "${BOLD}Archive Prompt${RESET}  ${DIM}(처리 완료)${RESET}"
@@ -350,10 +365,6 @@ render_archive_prompts() {
 
     echo -e "  ${GREEN}✓${RESET} ${DIM}${short_ts}${RESET}  ${detail}"
   done
-
-  if [ "$total_prompts" -gt 9 ]; then
-    echo -e "  ${DIM}… +$((total_prompts - 9)) more${RESET}"
-  fi
 }
 
 # ══════════════════════════════════════════
@@ -396,6 +407,9 @@ trap 'tput cnorm 2>/dev/null; exit 0' EXIT INT TERM
 clear
 
 while true; do
+  _ROWS=$(tput lines 2>/dev/null || echo 30)
+  _COLS=$(tput cols 2>/dev/null || echo 80)
+  export _ROWS _COLS
   buf=$(render_dashboard 2>&1)
   tput cup 0 0 2>/dev/null
   echo "$buf"

package/scripts/harness-monitor.sh

@@ -159,8 +159,14 @@ render_team_section() {
         case "$action" in
           gen|gen-start|gen-read|gen-write|gen-test|gen-done)
             a_icon="▶"; a_color="$GREEN"; a_label="Gen" ;;
-          eval|eval-start|eval-check|eval-done)
-            a_icon="✦"; a_color="$BLUE"; a_label="Eval" ;;
+          eval-start)
+            a_icon="✦"; a_color="$MAGENTA"; a_label="Eval" ;;
+          eval-check)
+            a_icon="·"; a_color="$MAGENTA"; a_label="Eval" ;;
+          eval-done)
+            a_icon="✦"; a_color="${BOLD}${MAGENTA}"; a_label="Eval" ;;
+          eval)
+            a_icon="✦"; a_color="$MAGENTA"; a_label="Eval" ;;
           result|pass)
             a_icon="✓"; a_color="$GREEN"; a_label="Result" ;;
           fail)

package/scripts/harness-prompt-history.sh

@@ -96,34 +96,30 @@ render_processing_status() {
   echo ""
 }
 
-# 사용자 프롬프트만 필터하여 표시
+# 사용자 프롬프트만 필터하여 표시 (newest first, 전체 출력)
 render_user_prompts() {
   if [ ! -f "$PROGRESS_LOG" ]; then
     echo -e "  ${DIM}(프롬프트 기록 없음)${RESET}"
     return
   fi
 
-  local term_height
-  term_height=$(tput lines 2>/dev/null || echo 30)
-  local max_lines=$((term_height - 10))
-  if [ "$max_lines" -lt 5 ]; then max_lines=5; fi
-
-  # user-prompt 행만 필터
+  # user-prompt 행만 필터 → tac으로 newest first
   local prompts
-  prompts=$(grep '| user-prompt |' "$PROGRESS_LOG" 2>/dev/null | tail -"$max_lines")
+  prompts=$(grep '| user-prompt |' "$PROGRESS_LOG" 2>/dev/null | tac)
 
   if [ -z "$prompts" ]; then
     echo -e "  ${DIM}(사용자 프롬프트 없음)${RESET}"
     return
   fi
 
-  local line_num=0
   local total_prompts
-  total_prompts=$(grep -c '| user-prompt |' "$PROGRESS_LOG" 2>/dev/null || echo 0)
+  total_prompts=$(echo "$prompts" | wc -l | tr -d ' ')
 
-  echo "$prompts" | while IFS= read -r line; do
-    line_num=$((line_num + 1))
+  # 터미널 폭: main loop에서 측정한 _COLS 사용 (subshell 내 tput 불가 대비)
+  local max_width=$(( ${_COLS:-80} - 12 ))
+  if [ "$max_width" -lt 20 ]; then max_width=20; fi
 
+  echo "$prompts" | while IFS= read -r line; do
     local ts detail
     ts=$(echo "$line" | awk -F'|' '{gsub(/^ +| +$/,"",$1); print $1}')
     detail=$(echo "$line" | awk -F'|' '{gsub(/^ +| +$/,"",$4); print $4}')
@@ -131,20 +127,10 @@ render_user_prompts() {
     local short_ts
     short_ts=$(echo "$ts" | grep -oE '[0-9]{2}:[0-9]{2}' | tail -1 || echo "$ts")
 
-    # 프롬프트 내용 truncate
-    local max_width
-    max_width=$(( $(tput cols 2>/dev/null || echo 40) - 12 ))
-    if [ "$max_width" -lt 20 ]; then max_width=20; fi
     if [ ${#detail} -gt "$max_width" ]; then
       detail="${detail:0:$((max_width - 2))}.."
     fi
 
-    # 처리 상태 찾기: 이 프롬프트 이후의 첫 번째 에이전트 액션
-    local processed_by=""
-    local prompt_ts_epoch
-    prompt_ts_epoch=$(echo "$ts" | sed 's/[^0-9:]//g')
-
-    # 간단히: 마지막 프롬프트인지 확인 → 현재 처리 중 표시
     echo -e "  ${DIM}${short_ts}${RESET}  ${WHITE}${detail}${RESET}"
   done
 
@@ -164,6 +150,10 @@ trap 'tput cnorm 2>/dev/null; exit 0' EXIT INT TERM
 clear
 
 while true; do
+  # subshell 내 tput 불가 → 미리 터미널 크기 측정
+  _ROWS=$(tput lines 2>/dev/null || echo 30)
+  _COLS=$(tput cols 2>/dev/null || echo 80)
+  export _ROWS _COLS
   buf=$(render_all 2>&1)
   tput cup 0 0 2>/dev/null
   echo "$buf"

package/scripts/init-agents-md.sh

@@ -5,6 +5,7 @@ set -e
 
 PROJECT_ROOT="${1:-.}"
 SCAN_RESULT="${PROJECT_ROOT}/.harness/actions/scan-result.json"
+export SCAN_RESULT PROJECT_ROOT
 AGENTS_FILE="${PROJECT_ROOT}/AGENTS.md"
 CLAUDE_FILE="${PROJECT_ROOT}/CLAUDE.md"
 BACKUP_DIR="${PROJECT_ROOT}/.harness/archive/pre-harness-backup"
@@ -128,6 +129,15 @@ tag_rules = {
     "tests": ("[TEST]", "Test Suite", "Evaluator"),
     "e2e": ("[TEST]", "E2E Tests", "Evaluator"),
     "__tests__": ("[TEST]", "Unit Tests", "Evaluator"),
+
+    # Native app patterns (Swift / Kotlin / Rust 등)
+    "Sources": ("[FE]", "Native Source Root", "Generator-Frontend"),
+    "Tests": ("[TEST]", "Native Test Suite", "Evaluator"),
+    "Resources": ("[FE]", "Native Resources", "Generator-Frontend"),
+    "android": ("[FE]", "Android Host", "Generator-Frontend"),
+    "ios": ("[FE]", "iOS Host", "Generator-Frontend"),
+    "macos": ("[FE]", "macOS Host", "Generator-Frontend"),
+    "Shared": ("[FE]", "Cross-platform Shared", "Generator-Frontend"),
 }
 
 # 디렉토리를 분석

package/scripts/init-ref-docs.sh

@@ -0,0 +1,262 @@
+#!/bin/bash
+# init-ref-docs.sh — 감지된 스택에 따라 .harness/ref/<role>-<stack>.md 를 준비한다.
+#
+# bash 혼자서는 Claude 의 WebSearch/WebFetch 를 호출할 수 없으므로 이 스크립트는:
+#   1. scan-result.json 에서 감지된 스택 목록을 계산
+#   2. --placeholder 모드: 최소 frontmatter + TODO 본문을 저장 (AC 검증용 · 파이프라인 unblock 용)
+#   3. --claude-prompt 모드: Claude 세션이 실제 WebSearch + WebFetch + synthesis 로 채울 수 있도록 프롬프트 템플릿을 stdout 출력
+#   4. --register 모드: Claude 가 실제 본문을 작성한 뒤 호출해 .generated.json 에 sources / generated_at 을 등록
+#
+# 사용 예:
+#   bash scripts/init-ref-docs.sh --dry-run .
+#   bash scripts/init-ref-docs.sh --yes --placeholder --stack swift --role fe .
+#   bash scripts/init-ref-docs.sh --claude-prompt --stack swift --role fe .
+#   bash scripts/init-ref-docs.sh --register --stack swift --role fe --sources "https://a,https://b" .
+set -e
+
+# ───── 옵션 파싱 ─────
+MODE="interactive"    # interactive | dry-run | placeholder | claude-prompt | register
+YES=false
+REFRESH=false
+STACK=""
+ROLE=""
+SOURCES=""
+PROJECT_ROOT="."
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --dry-run)        MODE="dry-run"; shift ;;
+    --placeholder)    MODE="placeholder"; shift ;;
+    --claude-prompt)  MODE="claude-prompt"; shift ;;
+    --register)       MODE="register"; shift ;;
+    --yes)            YES=true; shift ;;
+    --refresh)        REFRESH=true; shift ;;
+    --stack)          STACK="$2"; shift 2 ;;
+    --role)           ROLE="$2"; shift 2 ;;
+    --sources)        SOURCES="$2"; shift 2 ;;
+    -h|--help)
+      sed -n '2,16p' "$0" | sed 's/^# //; s/^#//'
+      exit 0 ;;
+    *)                PROJECT_ROOT="$1"; shift ;;
+  esac
+done
+
+SCAN="${PROJECT_ROOT}/.harness/actions/scan-result.json"
+REF_DIR="${PROJECT_ROOT}/.harness/ref"
+META="${REF_DIR}/.generated.json"
+ARCHIVE_DIR="${PROJECT_ROOT}/.harness/archive"
+mkdir -p "$REF_DIR" "$ARCHIVE_DIR"
+[ -f "$META" ] || echo "{}" > "$META"
+
+# ───── 감지된 스택 목록 ─────
+detect_stacks() {
+  if [ ! -f "$SCAN" ]; then
+    echo "ERROR: scan-result.json 이 없습니다. 먼저 bash scripts/scan-project.sh ${PROJECT_ROOT} 실행하세요." >&2
+    exit 1
+  fi
+  local fe be native
+  fe=$(jq -r '.tech_stack.frontend' "$SCAN")
+  be=$(jq -r '.tech_stack.backend' "$SCAN")
+  native=$(jq -r '.tech_stack.is_native_app // false' "$SCAN")
+
+  # 네이티브 앱은 fe 만 기록 (be 는 null)
+  if [ "$fe" != "unknown" ] && [ "$fe" != "null" ]; then
+    echo "fe:$fe"
+  fi
+  if [ "$native" != "true" ] && [ "$be" != "unknown" ] && [ "$be" != "null" ]; then
+    echo "be:$be"
+  fi
+}
+
+# ───── placeholder 본문 ─────
+write_placeholder() {
+  local role="$1" stack="$2" path="$3"
+  local ts
+  ts=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+  cat > "$path" <<REF
+---
+docmeta:
+  id: ref-${role}-${stack}
+  stack: ${stack}
+  role: ${role}
+  language: ${stack}
+  generated_at: ${ts}
+  generator: init-ref-docs.sh (placeholder)
+  sources: []
+  version: 0
+runner:
+  dev_command: null
+  start_command: null
+  install_command: null
+paths:
+  source_roots: []
+  test_roots: []
+  config_files: []
+api:
+  base_url: null
+  gateway: null
+validation:
+  pre_eval_gate: []
+  functional_tests: []
+  visual:
+    enabled: false
+    reason: "placeholder — not yet filled by Claude"
+    manual_check: "bash init.sh refresh-ref ${role} ${stack} 실행 후 Claude 세션에서 WebSearch + WebFetch 로 채우기"
+  anti_pattern_rules: []
+---
+
+# Ref — ${stack} (${role})
+
+> **Status**: PLACEHOLDER — Claude 가 WebSearch + WebFetch 로 채워야 함.
+> 실행: bash scripts/init-ref-docs.sh --claude-prompt --stack ${stack} --role ${role}
+
+## 1. Runner
+TODO
+
+## 2. Paths / Source Layout
+TODO
+
+## 3. Best Practices
+TODO
+
+## 4. Anti-Patterns (→ gotchas 시드 후보)
+TODO
+REF
+}
+
+# ───── Claude 용 프롬프트 ─────
+# React 계열 스택 (react / nextjs / vite-react) 일 때는
+# skills/generator-frontend/references/_web-react-legacy/ 의 4개 문서를
+# 로컬 seed 로 프롬프트에 포함시킨다. 이 seed 는 새 ref-docs 작성 시
+# "기존 웹 React 가이드" 참조용이며 WebSearch 결과와 병합된다.
+LEGACY_SEED_DIR="$(dirname "$0")/../skills/generator-frontend/references/_web-react-legacy"
+emit_claude_prompt() {
+  local role="$1" stack="$2" path="$3"
+  local legacy_hint=""
+  if [ "$role" = "fe" ] && [ -d "$LEGACY_SEED_DIR" ]; then
+    case "$stack" in
+      react|nextjs|vite-react|nuxt|vue|svelte|angular|*web*)
+        legacy_hint="
+Local seed (병합 대상 · 이미 검증된 웹/React best practice):
+$(ls "$LEGACY_SEED_DIR" 2>/dev/null | sed 's|^|  - '"$LEGACY_SEED_DIR"'/|')
+"
+        ;;
+    esac
+  fi
+  cat <<PROMPT
+───────────────────────────────────────────────
+Claude 세션에 아래 프롬프트를 전달하세요
+(또는 현재 세션이라면 그대로 실행):
+───────────────────────────────────────────────
+
+목표: ${path} 를 생성한다.
+
+1. WebSearch 로 다음 쿼리 실행: "${stack} best practices 2025 site:docs.*"
+2. 상위 3개 공식 문서 URL 을 WebFetch 로 가져온다.
+3. 결과를 종합해 다음 스키마로 YAML frontmatter + 본문을 작성한다:
+   - docmeta: { id, stack, role, language, generated_at, generator, sources, version }
+   - runner: { dev_command, start_command, install_command }
+   - paths: { source_roots, test_roots, config_files }
+   - api: { base_url, gateway }
+   - validation:
+       pre_eval_gate: [...]
+       functional_tests: [...]
+       visual: { enabled, reason, manual_check }
+       anti_pattern_rules: [{ id, pattern_type: "grep"|"lint_tool", pattern|tool+args, paths, severity }]
+4. 본문에는 Runner / Paths / Best Practices / Anti-Patterns 섹션 작성.
+5. 완료 후: bash scripts/init-ref-docs.sh --register --stack ${stack} --role ${role} --sources "<url1>,<url2>,<url3>" ${PROJECT_ROOT}
+${legacy_hint}
+───────────────────────────────────────────────
+PROMPT
+}
+
+# ───── register: 메타 기록 ─────
+register_meta() {
+  local role="$1" stack="$2" sources_csv="$3"
+  local ts key sources_json
+  ts=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+  key="${role}-${stack}"
+  sources_json=$(echo "$sources_csv" | awk -F',' 'BEGIN{printf "["} {for(i=1;i<=NF;i++){printf (i>1?",":"") "\"" $i "\""}} END{printf "]"}')
+  [ -z "$sources_csv" ] && sources_json="[]"
+  jq --arg k "$key" --arg ts "$ts" --argjson s "$sources_json" '.[$k] = {"generated_at": $ts, "sources": $s, "status": "filled"}' "$META" > "${META}.tmp" && mv "${META}.tmp" "$META"
+  echo "registered: $key (sources=$(echo "$sources_json" | jq 'length'))"
+}
+
+# ───── 한 스택 처리 ─────
+process_one() {
+  local role="$1" stack="$2"
+  local path="${REF_DIR}/${role}-${stack}.md"
+
+  if [ -f "$path" ] && ! $REFRESH; then
+    echo "skip: $path 이미 존재 (--refresh 로 강제 재생성)"
+    return 0
+  fi
+  if [ -f "$path" ] && $REFRESH; then
+    local backup="${ARCHIVE_DIR}/ref-${role}-${stack}-$(date +%Y%m%d%H%M%S).md"
+    cp "$path" "$backup"
+    echo "archived: $backup"
+  fi
+
+  local answer="y"
+  if ! $YES; then
+    printf "Generate ref-docs for %s-%s? [y/N] " "$role" "$stack"
+    read -r answer </dev/tty || answer="n"
+  fi
+  case "$answer" in
+    y|Y|yes|YES) ;;
+    *) echo "skipped: $role-$stack"; return 3 ;;
+  esac
+
+  case "$MODE" in
+    placeholder)
+      write_placeholder "$role" "$stack" "$path"
+      local ts; ts=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+      jq --arg k "${role}-${stack}" --arg ts "$ts" '.[$k] = {"generated_at": $ts, "sources": [], "status": "placeholder"}' "$META" > "${META}.tmp" && mv "${META}.tmp" "$META"
+      echo "wrote: $path (placeholder)"
+      ;;
+    claude-prompt)
+      emit_claude_prompt "$role" "$stack" "$path"
+      ;;
+    *)
+      echo "ERROR: interactive 모드는 --placeholder 또는 --claude-prompt 중 하나를 지정하세요." >&2
+      return 1
+      ;;
+  esac
+}
+
+# ───── main ─────
+case "$MODE" in
+  dry-run)
+    echo "detected stacks:"
+    detect_stacks | sed 's/^/  - /'
+    echo ""
+    echo "ref files 예상 경로 (미존재 시 생성 대상):"
+    while IFS=':' read -r role stack; do
+      path="${REF_DIR}/${role}-${stack}.md"
+      if [ -f "$path" ]; then
+        echo "  [exists] $path"
+      else
+        echo "  [create] $path"
+      fi
+    done < <(detect_stacks)
+    ;;
+  register)
+    [ -z "$STACK" ] || [ -z "$ROLE" ] && { echo "ERROR: --register 는 --stack --role --sources 필요" >&2; exit 1; }
+    register_meta "$ROLE" "$STACK" "$SOURCES"
+    ;;
+  placeholder|claude-prompt)
+    if [ -n "$STACK" ] && [ -n "$ROLE" ]; then
+      process_one "$ROLE" "$STACK"
+    else
+      # 감지된 전체 스택을 순회
+      while IFS=':' read -r role stack; do
+        process_one "$role" "$stack"
+      done < <(detect_stacks)
+    fi
+    ;;
+  interactive)
+    echo "ERROR: 모드 지정 필요 — --dry-run | --placeholder | --claude-prompt | --register" >&2
+    echo "자세한 사용법: bash $0 --help" >&2
+    exit 1
+    ;;
+esac

package/scripts/scan-project.sh

@@ -39,6 +39,7 @@ TECH_FRONTEND="unknown"
 TECH_DB="unknown"
 TECH_MONOREPO="none"
 TECH_LANG="unknown"
+IS_NATIVE_APP=false
 
 # Backend
 if [ -f "${PROJECT_ROOT}/nest-cli.json" ]; then
@@ -130,6 +131,42 @@ if [ "$FE_STACK" = "flutter" ] && [ -n "$FLUTTER_ROOT" ]; then
   fi
 fi
 
+# Swift (macOS / iOS 네이티브 앱) 감지 — Flutter 감지 이후
+if [ "$TECH_FRONTEND" = "unknown" ]; then
+  SWIFT_DETECTED=false
+  if [ -f "${PROJECT_ROOT}/Package.swift" ]; then
+    SWIFT_DETECTED=true
+  fi
+  if ! $SWIFT_DETECTED; then
+    for f in "${PROJECT_ROOT}"/*.xcodeproj "${PROJECT_ROOT}"/*.xcworkspace; do
+      if [ -e "$f" ]; then
+        SWIFT_DETECTED=true
+        break
+      fi
+    done
+  fi
+  if ! $SWIFT_DETECTED && [ -f "${PROJECT_ROOT}/Podfile" ]; then
+    SWIFT_DETECTED=true
+  fi
+
+  if $SWIFT_DETECTED; then
+    TECH_LANG="swift"
+    IS_NATIVE_APP=true
+    FE_STACK="swift"       # FE_STACK 기본값(react) 을 Swift 로 치환
+    FE_TARGET="native"     # web/mobile/desktop 대신 native
+    # 서브타입 판별 — NSStatusBar 가 가장 특화적이므로 우선
+    if grep -rq "NSStatusBar.system" "${PROJECT_ROOT}" --include="*.swift" 2>/dev/null; then
+      TECH_FRONTEND="swift-macos-statusbar"
+    elif grep -rq "import SwiftUI" "${PROJECT_ROOT}" --include="*.swift" 2>/dev/null; then
+      TECH_FRONTEND="swift-swiftui"
+    elif grep -rq "import UIKit" "${PROJECT_ROOT}" --include="*.swift" 2>/dev/null; then
+      TECH_FRONTEND="swift-uikit"
+    else
+      TECH_FRONTEND="swift"
+    fi
+  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
@@ -257,9 +294,18 @@ cat > "$OUTPUT" << JSONEOF
     "fe_target": "${FE_TARGET}",
     "database": "${TECH_DB}",
     "monorepo": "${TECH_MONOREPO}",
-    "language": "${TECH_LANG}"
+    "language": "${TECH_LANG}",
+    "is_native_app": ${IS_NATIVE_APP}
   },
 
+  "tech_stack_confidence": "$(
+    if [ "$TECH_BACKEND" = "unknown" ] && [ "$TECH_FRONTEND" = "unknown" ]; then
+      echo "unknown"
+    else
+      echo "detected"
+    fi
+  )",
+
   "structure": {
     "directories": ${TREE_JSON},
     "config_files": ${CONFIG_FILES}
@@ -312,7 +358,7 @@ echo "=== Scan Complete ==="
 echo "Output: ${OUTPUT}"
 echo ""
 echo "--- Summary ---"
-echo "Tech Stack: ${TECH_BACKEND} / ${TECH_FRONTEND} (fe_stack=${FE_STACK}, fe_target=${FE_TARGET}) / ${TECH_DB}"
+echo "Tech Stack: ${TECH_BACKEND} / ${TECH_FRONTEND} (fe_stack=${FE_STACK}, fe_target=${FE_TARGET}, native=${IS_NATIVE_APP}) / ${TECH_DB}"
 echo "Monorepo: ${TECH_MONOREPO}"
 echo "OpenAPI: ${OPENAPI}"
 echo "Git: ${GIT_INIT} (${GIT_COMMITS} commits, branch: ${GIT_BRANCH})"

package/skills/dispatcher/SKILL.md

@@ -113,13 +113,11 @@ AGENTS.md 비하네스  → 기존 백업 + 리빌드
 
 ### fe_stack 필드 (FE 파이프라인에서 필수)
 
-FE-ONLY 또는 FULLSTACK 선택 시, `pipeline.json`에 **`fe_stack`** 필드를 포함해야 한다:
+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`
+- `scan-result.json.tech_stack.fe_stack` (또는 `tech_stack.frontend`) 값을 기본으로 사용
+- 값이 없거나 불명확하면 Planner 가 확정하도록 위임 (Dispatcher 는 `"unknown"` 기록 + `notes` 에 메모)
+- v5.2 이후: **에이전트 분기 없음** — 동일한 `generator-frontend` / `evaluator-functional` 에이전트가 `.harness/ref/fe-<fe_stack>.md` 를 로드해 스택 적응적으로 동작
 
 ## 6. Brainstormer Routing Decision
 
@@ -174,7 +172,7 @@ Planner 를 호출해야 한다고 판단되면, **사용자에게 단 하나의
 | 상황 | next_agent |
 |------|-----------|
 | "Eval, X 다시 검증해" | `evaluator-functional` (또는 `evaluator-visual`) |
-| "Generator-FE, Y 버그 고쳐" | `generator-frontend` (또는 Flutter 변형) |
+| "Generator-FE, Y 버그 고쳐" | `generator-frontend` |
 | "Generator-BE, API 재생성해" | `generator-backend` |
 | Eval FAIL → retry | `failure.retry_target` |
 | Gotcha 수정 | `failure.retry_target` 또는 현재 에이전트 |
@@ -192,14 +190,48 @@ Planner 를 호출해야 한다고 판단되면, **사용자에게 단 하나의
 이 경우 기존 `.harness/actions/brainstorm-spec.md` 는 Brainstormer 의 On Start 에서
 `.harness/archive/brainstorm-spec-<timestamp>.md` 로 백업된다.
 
-## 7. Handoff 라우팅 (fe_stack 반영)
+## 7. Handoff 라우팅 (v5.2 — 스택 치환 없음)
 
-Dispatcher가 `next_agent` 를 세팅할 때 pipeline.json.fe_stack 을 참조해 치환:
+v5.2 이후 에이전트 치환은 사용하지 않는다. Dispatcher 가 `next_agent` 를 세팅할 때 `pipeline.json.fe_stack` 은 **참고용 메타데이터**로만 기록되고, 실제 스택별 행동은 에이전트가 자기 On Start 에서 `.harness/ref/<role>-<stack>.md` 를 로드해 결정한다.
 
-| 원본 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 → 다음 단계로 이동) |
+| 에이전트 | 스택 적응 메커니즘 |
+|---------|------------------|
+| `generator-frontend` | On Start 에서 `.harness/ref/fe-<stack>.md` 로드 |
+| `generator-backend` | On Start 에서 `.harness/ref/be-<stack>.md` 로드 |
+| `evaluator-functional` | `ref.validation.pre_eval_gate` / `functional_tests` / `anti_pattern_rules` 실행 |
+| `evaluator-visual` | `ref.validation.visual.enabled == false` 면 MANUAL_REQUIRED 로 skip |
 
-**Brainstormer 는 fe_stack 치환 대상이 아니다** — 언어/스택 무관 공통 에이전트.
+## 8. Auto Gotcha Registration (v5.2)
+
+evaluator-functional / evaluator-visual 이 안티패턴을 발견하면 Dispatcher 경유로 자동 gotcha 파일에 등록한다. 이 섹션은 Dispatcher 가 등록 이벤트를 받았을 때의 행동을 정의한다.
+
+### 8.1 수신 이벤트 페이로드
+
+`api-contract.json.contracts["gotcha_register_interface"]` 참조. 필수 필드:
+- `agent` (예: `"generator-frontend"`)
+- `stack` (예: `"swift"`)
+- `rule_id`, `severity`, `occurrences[] (file/line/snippet)`, `source_feature`
+
+### 8.2 대상 파일 결정
+
+`.harness/gotchas/<agent>-<stack>.md` (없으면 생성). 스택 특정 규칙이 아닌 공통 규칙은 `<agent>.md` 로 라우팅 (gotcha-flow.md 의 "라우팅 규칙" 참조).
+
+### 8.3 등록 절차
+
+```
+1. 대상 파일 열기 (없으면 표준 헤더로 생성)
+2. 기존 항목 중 같은 rule_id 검색:
+   - 있음 → Occurrences +1, Last seen 업데이트, snippet 최신으로 교체
+   - 없음 → 다음 G-NNN 번호로 새 항목 추가
+3. progress.log 에 `"auto_gotcha_registered"` 이벤트 기록
+4. evaluation-*.md 에 "Registered gotchas: <G-IDs>" 요약 기록
+```
+
+항목 포맷은 gotcha-flow.md 의 "Gotcha 항목 형식" 섹션과 동일.
+
+### 8.4 멱등성 / 중복 방지
+
+- 동일 feature 의 동일 rule_id 는 한 번의 평가 안에서 최대 1회만 Occurrences 증가
+- Retry 시에는 이전 Occurrences 유지 (재평가이므로 중복 카운팅 금지)
+
+**Brainstormer 는 스택 치환 대상이 아니다** — 언어/스택 무관 공통 에이전트.

package/skills/dispatcher/references/gotcha-flow.md

@@ -24,9 +24,36 @@
 | 설계, 아키텍처, 기획, 기능 목록, IA, 서비스 분할 | `planner` |
 | 불명확 | 사용자에게 질문 |
 
+## 스택별 파일 네이밍 규칙 (v5.2 — 적응형 하네스)
+
+에이전트별로 **공통 파일 + 스택별 파일** 2트랙:
+
+| 파일 | 용도 |
+|------|------|
+| `.harness/gotchas/<agent>.md` | 스택 무관 공통 실수 (예: "PASS 남발", "Evidence 없는 Score") |
+| `.harness/gotchas/<agent>-<stack>.md` | 특정 스택에서만 적용되는 실수 (예: `generator-frontend-swift.md` — force unwrap 금지) |
+
+### 라우팅 규칙
+
+교정 시그널을 기록할 때:
+1. `scan-result.json.tech_stack.fe_stack` / `be_stack` 조회
+2. 시그널 내용이 스택 특정 기술(import, API, 프레임워크 함수명 등)을 언급 → `<agent>-<stack>.md`
+3. 스택 무관 일반 규칙(문서화, 테스트 태도, 평가 기준) → `<agent>.md` (공통)
+4. 판단 애매 → **공통 파일 우선** (후속 발생 시 스택별로 이관)
+
+### 에이전트 On Start 로딩
+
+적응형 에이전트는 세션 시작 시 **두 파일을 모두 로드**:
+```
+.harness/gotchas/<agent>.md              # 공통
+.harness/gotchas/<agent>-<current_stack>.md   # 스택별 (없으면 skip)
+```
+
+---
+
 ## Gotcha 항목 형식
 
-`.harness/gotchas/[agent-name].md`에 추가:
+`.harness/gotchas/[agent-name].md` 또는 `<agent-name>-<stack>.md` 에 추가:
 
 ```markdown
 ### [G-NNN] 간결한 제목

package/skills/evaluator-functional/SKILL.md

@@ -86,6 +86,38 @@ FEEDBACK: one paragraph summary
 ---END-EVAL-RESULT---
 ```
 
+## Stack-Adaptive Validation (v5.2)
+
+Evaluator 는 스택마다 다른 검증 도구를 가진다. `scan-result.json.tech_stack` 에서 현재 스택을 확인한 뒤 `.harness/ref/<role>-<stack>.md` 의 `validation` 블록을 로드해 순차 실행한다.
+
+### Validation 블록 파싱
+
+```
+1. ref-docs YAML frontmatter 파싱 → validation 객체 추출
+2. validation.pre_eval_gate 의 모든 명령을 순차 실행
+   - 실패 시 → FAIL + generator 로 retry (Pre-Eval Gate)
+3. validation.functional_tests 의 모든 명령을 순차 실행
+   - 실패 시 → FAIL 항목 기록
+4. validation.anti_pattern_rules 순회:
+   - pattern_type == "grep":   `grep -rE "<pattern>" <paths>` 로 스캔
+   - pattern_type == "lint_tool": `<tool> <args>` 로 호출 + JSON 출력 파싱
+   - 위반 발견 시 → Auto Gotcha Registration (아래)
+5. validation.visual.enabled:
+   - true  → evaluator-visual 에 Playwright 검증 위임
+   - false → evaluation-functional.md 에 "MANUAL_REQUIRED: {manual_check}" 기록, Visual 은 __skip__
+```
+
+### Auto Gotcha Registration (안티패턴 자동 등록)
+
+`validation.anti_pattern_rules` 실행에서 위반 1건 이상 발견 시 — Dispatcher 경유로 자동 gotcha 등록:
+
+- 대상 파일: `.harness/gotchas/generator-<role>-<stack>.md` (없으면 생성)
+- 항목 포맷: `### [G-NNN] <rule_id>` / severity / occurrences / last_seen(file:line) / snippet / source feature
+- 중복 rule_id: Occurrences 카운터 +1 + last_seen 업데이트
+- 상세 계약: `api-contract.json.contracts["gotcha_register_interface"]`
+
+이 메커니즘이 작동하려면 Dispatcher 의 "Auto Gotcha Registration" 섹션을 참고하라.
+
 ## Evaluation Steps
 
 ### Step 0: IA Structure Compliance (GATE)

package/skills/evaluator-visual/SKILL.md

@@ -49,7 +49,25 @@ disable-model-invocation: true
 2. `.harness/gotchas/evaluator-visual.md` 읽기 — **과거 실수 반복 금지**
 3. `.harness/memory.md` 읽기 — **프로젝트 공유 학습 규칙 적용**
 4. `actions/evaluation-functional.md` — Verdict: PASS 확인
-5. Frontend `http://localhost:5173` 실행 확인
+5. **Stack-Adaptive Gate** (v5.2) — `scan-result.json.tech_stack` 으로 스택 확인 후 `.harness/ref/fe-<stack>.md` 의 `validation.visual` 파싱:
+   - `visual.enabled == false`: 즉시 **MANUAL_REQUIRED 모드** 로 전환 — 아래 "Visual Skip Flow" 수행 후 종료
+   - `visual.enabled == true` (또는 ref-docs 없이 웹 전통 스택): 계속 진행, ref 에 `visual.base_url` 이 있으면 그 URL 로, 없으면 `ref.runner.dev_command` 로 서버 기동 후 Playwright 접속
+
+## Visual Skip Flow (네이티브 앱 / 비-브라우저 스택)
+
+`validation.visual.enabled == false` (예: Swift macOS, Flutter mobile, CLI 앱) 인 경우:
+
+1. Playwright 스크린샷·axe-core·AI슬롭 감지 **전부 skip**
+2. `.harness/actions/evaluation-visual.md` 에 다음을 기록:
+   ```
+   VERDICT: MANUAL_REQUIRED
+   STACK: <stack>
+   REASON: {ref.validation.visual.reason}
+   MANUAL_CHECK: {ref.validation.visual.manual_check}
+   ```
+3. progress.json: `agent_status = "completed"`, `next_agent = "archive"` (PASS 경로와 동일 라우팅)
+4. `progress.log` 에 `"visual skipped (manual required)"` 이벤트 기록
+5. 사용자에게 `manual_check` 문자열 출력 + 확인 요청
 
 ## Evaluation Steps
 

package/skills/generator-backend/SKILL.md

@@ -1,62 +1,98 @@
 ---
 name: harness-generator-backend
-description: "하네스 Backend Generator. NestJS MSA 모노레포로 API Gateway, Microservices, DB 스키마를 구현한다. api-contract.json이 스펙이며, Sprint Contract의 Backend 섹션을 작성 후 구현한다."
+description: "하네스 Backend Generator. 스택 독립(adaptive) — scan-result.json 의 be_stack / language 에 따라 .harness/ref/be-<stack>.md 를 로드해 runner/paths/api/validation 을 따른다. 모든 BE 스택(FastAPI / Django / Go / Rails / Phoenix / Spring / Express 등) 대응."
 disable-model-invocation: true
 ---
 
-# Generator-Backend — NestJS MSA
+# Generator-Backend — Adaptive (Stack-Agnostic)
 
 ## Session Boundary Protocol
 
 ### On Start
-1. `.harness/progress.json` 읽기 — `next_agent`가 `"generator-backend"`인지 확인
+1. `.harness/progress.json` 읽기 — `next_agent` 가 `"generator-backend"` 인지 확인
 2. progress.json 업데이트: `current_agent` → `"generator-backend"`, `agent_status` → `"running"`, `updated_at` 갱신
-3. `failure` 필드 확인 — retry인 경우 `evaluation-functional.md`의 실패 사유 우선 읽기
+3. `failure` 필드 확인 — retry 인 경우 평가 문서의 실패 사유 우선 읽기
 
 ### On Complete
 1. progress.json 업데이트:
    - `agent_status` → `"completed"`
-   - `completed_agents`에 `"generator-backend"` 추가
-   - `next_agent` → 파이프라인에 따라 결정 (FULLSTACK: `"generator-frontend"`, BE-ONLY: `"evaluator-functional"`)
+   - `completed_agents` 에 `"generator-backend"` 추가
+   - `next_agent` → 파이프라인에 따라 (`"generator-frontend"` 또는 `"evaluator-functional"`)
    - `failure` 필드 초기화 (retry 성공 시)
-2. `feature-list.json`의 해당 feature `passes`에 `"generator-backend"` 추가
-3. `.harness/progress.log`에 요약 추가
+2. `feature-list.json` 의 해당 feature `passes` 에 `"generator-backend"` 추가
+3. `.harness/progress.log` 에 요약 추가
 4. **STOP. 다음 에이전트를 직접 호출하지 않는다.**
 5. 출력: `"✓ Generator-Backend 완료. bash scripts/harness-next.sh 실행하여 다음 단계 확인."`
 
-## Startup
+## Startup (Adaptive Loading)
 
 1. `AGENTS.md` 읽기 — IA-MAP, 권한 확인
-2. `.harness/gotchas/generator-backend.md` 읽기 — **과거 실수 반복 금지**
-3. `.harness/memory.md` 읽기 — **프로젝트 공유 학습 규칙 적용**
-4. `pwd` + `.harness/progress.json` + `git log --oneline -20`
-5. `.harness/actions/api-contract.json` 읽기 — **이것이 스펙**
-6. `.harness/actions/feature-list.json` — `layer: "backend"` 필터
-7. 통합 러너: `npm run dev`
-8. Gateway 헬스체크: `curl http://localhost:3000/health`
+2. `.harness/actions/scan-result.json` 읽기 → `tech_stack.backend` 또는 `tech_stack.language` 로 현재 스택 확정 (이하 `<stack>`)
+3. **Ref-docs 로드** — `.harness/ref/be-<stack>.md`
+   - 파일 없음 → STOP + 안내: `"ref-docs 가 없습니다. bash init.sh init 실행 또는 bash scripts/init-ref-docs.sh --claude-prompt --stack <stack> --role be . 실행하세요."`
+   - frontmatter 파싱 실패 → 경고 출력 + 기본값으로 degrade
+4. **Gotchas 로드** — 두 파일 모두 (있는 것만):
+   - `.harness/gotchas/generator-backend.md` (공통)
+   - `.harness/gotchas/generator-backend-<stack>.md` (스택별)
+5. `.harness/memory.md` 읽기 — 프로젝트 공유 학습 규칙
+6. `pwd` + `.harness/progress.json` + `git log --oneline -20`
+7. `.harness/actions/api-contract.json` 읽기 — **이 계약이 유일한 BE 외부 인터페이스**
+8. `.harness/actions/feature-list.json` — 지정된 `FEATURE_ID` 또는 `layer: "backend"` 필터
+9. **DB / 외부 의존성 부트스트랩**:
+   - `ref.runner.install_command` 가 있으면 1회 실행
+   - `ref.runner.dev_command` 를 백그라운드 실행 (있는 경우)
+
+## Feature-Level Mode (Team Mode)
+
+Team Worker 가 호출할 때 프롬프트에 `FEATURE_ID` 가 지정된다. Feature branch 에서 단일 feature 만 구현.
 
 ## AGENTS.md — 읽기 전용
 
-`[BE]` + `→ Generator-Backend` 소유 경로만 쓰기 가능. 구조 변경 필요 시 sprint-contract.md에 `## Change Request`.
+`[BE]` + `→ Generator-Backend` 소유 경로만 쓰기 가능. 스택별 실제 소스 경로는 `ref.paths.source_roots` 가 권위 있는 출처 (예: FastAPI `app/`, Go `cmd/` + `internal/`, Rails `app/`).
 
 ## Sprint Workflow
 
-1. **Sprint Contract BE 섹션 작성** — 엔드포인트, DB 변경, message patterns, 성공 기준
-2. **구현** — Gateway 컨트롤러 + Microservice 핸들러 + Shared DTO
-3. **Self-Verification** — Jest + curl 테스트
-4. **Handoff** → Generator-Frontend
+1. **Sprint Contract BE 섹션 추가** — 엔드포인트 / DB 스키마 / 서비스 분할 / 성공 기준
+2. **구현** — api-contract.json ↔ 해당 스택 타입 시스템 1:1 매핑
+3. **Self-Verification** — `ref.validation.pre_eval_gate` 의 모든 명령 실행
+4. **Handoff** → Evaluator-Functional (또는 Generator-Frontend, 파이프라인에 따라)
+
+## 스택 치환 규칙 (Adaptive Core)
+
+구현 시 **모든 스택 의존 값은 ref-docs 에서 치환**한다:
+
+| 치환 키 | 출처 | 예시 |
+|---------|------|------|
+| `<source_roots>` | `ref.paths.source_roots` | FastAPI: `app/` · Go: `cmd/`, `internal/` · Rails: `app/` |
+| `<test_roots>` | `ref.paths.test_roots` | FastAPI: `tests/` · Go: `_test.go` 동거 · Rails: `spec/` |
+| `<dev_command>` | `ref.runner.dev_command` | FastAPI: `uvicorn app.main:app` · Go: `go run ./cmd/server` |
+| `<api_base_url>` | `ref.api.base_url` | 로컬 개발 baseurl (ref-docs 참조) |
+| `<pre_eval_gate>` | `ref.validation.pre_eval_gate` | FastAPI: `[ruff, mypy, pytest]` · Go: `[go vet, go test ./...]` |
+| `<anti_patterns>` | `ref.validation.anti_pattern_rules` | 스택별 grep/lint 규칙 |
+
+api-contract.json 의 DTO 스키마는 해당 스택의 타입 표현(Pydantic / struct / class-validator / ActiveRecord 등)으로 직접 매핑한다.
+
+## 서비스 간 통신 규칙
+
+- MSA 환경이면 서비스 간 **직접 DB 접근 금지** (메시지 큐 / 이벤트 / RPC 만)
+- 모놀리스 환경이면 modules/packages 경계 준수
+- 어느 쪽인지 `ref.paths.source_roots` 구조와 `ref` 본문의 "Architecture" 섹션으로 판단
+
+## 핵심 규칙 (스택 무관)
 
-NestJS MSA 패턴 → [NestJS MSA 참조](references/nestjs-msa-patterns.md)
-Sprint Contract 형식 → [Sprint Contract BE 템플릿](references/sprint-contract-be.md)
+- api-contract.json 에 없는 엔드포인트 **구현 금지**
+- 로깅 / 에러 핸들링 / 트랜잭션 경계 필수
+- 보안: OWASP Top 10 (인증·인가·입력 검증·SQL Injection 등) 기본 준수
+- 테스트: `ref.validation.functional_tests` 에 나열된 명령이 전부 통과해야 PASS
 
 ## 금지 사항
 
-- api-contract.json에 없는 엔드포인트 추가
-- Frontend(apps/web/) 코드 수정
-- feature-list.json에서 `passes` 외 필드 수정
-- 서비스 간 직접 DB 접근 (반드시 메시지 패턴)
-- AGENTS.md 수정
+- **ref.paths.source_roots 밖의 프로덕션 코드 수정** (FE/HARNESS 영역 침범 금지)
+- api-contract.json 에 없는 엔드포인트 신설
+- `.harness/ref/` 직접 편집 (refresh 는 `bash init.sh refresh-ref` 경유)
+- 공통 `generator-backend.md` / 스택별 `generator-backend-<stack>.md` gotcha 에 적힌 실수 반복
 
-## On Evaluator Feedback
+## 디버깅 / Fallback
 
-`evaluation-functional.md` → `failure_location: "backend"` 필터 → 수정 → Jest 재실행 → 핸드오프
+- `ref-docs` 가 placeholder 상태 → 본격 구현 전에 `bash init.sh refresh-ref be <stack>` 으로 채우기 권고
+- `scan-result.json.tech_stack_confidence == "unknown"` → 사용자에게 객관식 + 자유입력 fallback 로 스택 확인 요청

package/skills/generator-frontend/SKILL.md

@@ -1,95 +1,102 @@
 ---
 name: harness-generator-frontend
-description: "하네스 Frontend Generator. React/Next.js + TypeScript로 프리미엄 UI를 구현한다. Vercel best practices(RSC, App Router, Cache Components) + taste-skill 디자인 철학(AI슬롭 금지, 프리미엄 타이포·컬러·모션) 기반. api-contract.json으로 Gateway만 바라본다."
+description: "하네스 Frontend Generator. 스택 독립(adaptive) — scan-result.json 의 fe_stack 에 따라 .harness/ref/fe-<stack>.md 를 로드해 해당 스택의 runner/paths/api/validation 을 따른다. 모든 FE 스택(Swift / Flutter / Vue / Svelte / Angular / 웹 SSR 등) 대응."
 disable-model-invocation: true
 ---
 
-# Generator-Frontend — React/Next.js + Premium Design
+# Generator-Frontend — Adaptive (Stack-Agnostic)
 
 ## Session Boundary Protocol
 
 ### On Start
-1. `.harness/progress.json` 읽기 — `next_agent`가 `"generator-frontend"`인지 확인
+1. `.harness/progress.json` 읽기 — `next_agent` 가 `"generator-frontend"` 인지 확인
 2. progress.json 업데이트: `current_agent` → `"generator-frontend"`, `agent_status` → `"running"`, `updated_at` 갱신
-3. `failure` 필드 확인 — retry인 경우 평가 문서의 실패 사유 우선 읽기
+3. `failure` 필드 확인 — retry 인 경우 평가 문서의 실패 사유 우선 읽기
 
 ### On Complete
 1. progress.json 업데이트:
    - `agent_status` → `"completed"`
-   - `completed_agents`에 `"generator-frontend"` 추가
+   - `completed_agents` 에 `"generator-frontend"` 추가
    - `next_agent` → `"evaluator-functional"`
    - `failure` 필드 초기화 (retry 성공 시)
-2. `feature-list.json`의 해당 feature `passes`에 `"generator-frontend"` 추가
-3. `.harness/progress.log`에 요약 추가
+2. `feature-list.json` 의 해당 feature `passes` 에 `"generator-frontend"` 추가
+3. `.harness/progress.log` 에 요약 추가
 4. **STOP. 다음 에이전트를 직접 호출하지 않는다.**
 5. 출력: `"✓ Generator-Frontend 완료. bash scripts/harness-next.sh 실행하여 다음 단계 확인."`
 
-## Startup
+## Startup (Adaptive Loading)
 
 1. `AGENTS.md` 읽기 — IA-MAP, 권한 확인
-2. `.harness/gotchas/generator-frontend.md` 읽기 — **과거 실수 반복 금지**
-3. `.harness/memory.md` 읽기 — **프로젝트 공유 학습 규칙 적용**
-4. `pwd` + `.harness/progress.json` + `git log --oneline -20`
-5. `.harness/actions/api-contract.json` 읽기 — **Gateway가 유일한 API 인터페이스**
-6. `.harness/actions/feature-list.json` — `layer: "frontend"` 필터
-7. Gateway 확인: `curl -s http://localhost:3000/health`
-8. Frontend 시작: `cd apps/web && npm run dev`
-
-## AGENTS.md — 읽기 전용
-
-`[FE]` + `→ Generator-Frontend` 소유 경로만 쓰기 가능.
-
-## Prerequisites
-
-**Backend 통합 러너가 동작 중이어야 함.** Gateway 미응답 시 → STOP.
+2. `.harness/actions/scan-result.json` 읽기 → `tech_stack.fe_stack` 또는 `tech_stack.frontend` 로 현재 스택 확정 (이하 `<stack>`)
+3. **Ref-docs 로드** — `.harness/ref/fe-<stack>.md`
+   - 파일 없음 → STOP + 안내: `"ref-docs 가 없습니다. bash init.sh init 실행 또는 bash scripts/init-ref-docs.sh --claude-prompt --stack <stack> --role fe . 실행하세요."`
+   - frontmatter 파싱 실패 → 경고 출력 + 기본값(runner/paths/api 모두 null)으로 degrade
+4. **Gotchas 로드** — 두 파일 모두 (있는 것만):
+   - `.harness/gotchas/generator-frontend.md` (공통)
+   - `.harness/gotchas/generator-frontend-<stack>.md` (스택별)
+5. `.harness/memory.md` 읽기 — 프로젝트 공유 학습 규칙
+6. `pwd` + `.harness/progress.json` + `git log --oneline -20`
+7. `.harness/actions/api-contract.json` 읽기
+8. `.harness/actions/feature-list.json` — 지정된 `FEATURE_ID` 또는 `layer: "frontend"` 필터
+9. **개발 서버 기동**:
+   - `ref.runner.dev_command` 가 `null` 이 아니면 해당 명령 백그라운드 실행
+   - `null` 이면 "개발 서버 기동은 스택 특성상 생략" 로그만 남김
+10. **API Gateway 체크**:
+    - `ref.api.base_url` 이 `null` 이 아니면 `curl -s <base_url>/health` 로 헬스체크
+    - `null` (네이티브 앱 등) 이면 체크 스킵
 
 ## Feature-Level Mode (Team Mode)
 
-Team Mode에서 Team Worker가 호출할 때, 프롬프트에 `FEATURE_ID`가 지정된다.
+Team Mode 에서 Team Worker 가 호출할 때, 프롬프트에 `FEATURE_ID` 가 지정된다.
 
 ### Feature-Level Rules
-- `feature-list.json`에서 **지정된 FEATURE_ID만** 필터하여 구현
-- 다른 Feature의 코드를 수정하지 않음
-- `depends_on`에 명시된 Feature는 이미 구현/머지 완료된 상태
-- Feature branch (`feature/F-XXX`)에서 작업, 완료 시 commit
-- Sprint Contract는 작성하지 않음 (v4에서는 Feature 단위로 관리)
-
-### Feature-Level Prompt Template
-Worker가 전달하는 프롬프트에는 다음이 포함됨:
-- `FEATURE_ID`, `feature_name`, `description`, `ac` (Acceptance Criteria)
-- `depends_on` (이미 완료된 의존 Feature 목록)
-- Eval 재시도 시: 이전 Eval의 피드백
+- `feature-list.json` 에서 **지정된 FEATURE_ID 만** 필터하여 구현
+- 다른 Feature 의 코드를 수정하지 않음
+- `depends_on` 에 명시된 Feature 는 이미 구현/머지 완료 상태
+- Feature branch (`feature/F-XXX`) 에서 작업, 완료 시 commit
+
+## AGENTS.md — 읽기 전용
+
+`[FE]` + `→ Generator-Frontend` 소유 경로만 쓰기 가능.
+스택별 실제 소스 경로는 `ref.paths.source_roots` 를 권위 있는 출처로 삼는다 (예: Swift `Sources/`, Flutter `lib/`, Vue `src/`).
 
 ## Sprint Workflow
 
-1. **Sprint Contract FE 섹션 추가** — 컴포넌트, API 연동, 성공 기준
-2. **구현** — 아래 3개 레퍼런스를 반드시 참조
-3. **Self-Verification** — tsc + Vitest + 브라우저 확인
+1. **Sprint Contract FE 섹션 추가** — 컴포넌트 / API 연동 / 성공 기준
+2. **구현** — 아래 "스택 치환 규칙" 엄수
+3. **Self-Verification** — `ref.validation.pre_eval_gate` 에 나열된 명령 전부 실행
 4. **Handoff** → Evaluator-Functional
 
-## 개발론 레퍼런스 (점진적 로딩)
+## 스택 치환 규칙 (Adaptive Core)
+
+구현 시 **모든 스택 의존 값은 ref-docs 에서 치환**한다:
 
-| 문서 | 내용 | 언제 로드 |
-|------|------|----------|
-| [Vercel Best Practices](references/vercel-best-practices.md) | RSC, App Router, 성능, 렌더링 전략 | 프로젝트 스캐폴딩 시 |
-| [Design System Rules](references/design-system-rules.md) | 타이포, 컬러, 레이아웃, 모션, 한국어 규칙 | 컴포넌트 구현 시 |
-| [AI Forbidden Patterns](references/ai-forbidden-patterns.md) | AI슬롭 감지/금지 패턴 전체 목록 | 구현 완료 후 셀프 체크 |
-| [Component Patterns](references/component-patterns.md) | 프로젝트 구조, API 타입, 상태관리 | 파일 생성 시 |
+| 치환 키 | 출처 | 예시 값 |
+|---------|------|---------|
+| `<source_roots>` | `ref.paths.source_roots` | Swift: `Sources/` · Flutter: `lib/` · Vue: `src/` |
+| `<test_roots>` | `ref.paths.test_roots` | Swift: `Tests/` · Flutter: `test/` · 일반 웹: `tests/` |
+| `<dev_command>` | `ref.runner.dev_command` | Swift: `xcodebuild -scheme X build` · 기타: ref-docs 참조 |
+| `<api_base_url>` | `ref.api.base_url` | 네이티브 앱: `null` (무시) · 웹: ref-docs 참조 |
+| `<pre_eval_gate>` | `ref.validation.pre_eval_gate` | Swift: `[swift build, swiftlint]` |
+| `<anti_patterns>` | `ref.validation.anti_pattern_rules` | 스택별 grep/lint 규칙 |
 
-## 핵심 규칙
+코드 생성 시 특정 프레임워크 전용 지시(예: "컴포넌트를 X 스타일로 만들어라")는 하지 않는다. 대신 ref-docs 본문의 "Best Practices" 섹션을 존중하여 해당 스택 이디엄으로 작성한다.
 
-- api-contract.json → `src/api/types.ts` 1:1 변환
-- API base URL: Gateway만 (`http://localhost:3000`)
-- **RSC 우선**: `'use client'`는 인터랙션이 필요한 곳만
-- 로딩/에러/빈 상태 3가지 필수 처리
-- 시맨틱 HTML + 키보드 네비게이션 + WCAG AA
-- Tailwind CSS + `cubic-bezier(0.16, 1, 0.3, 1)` 모션 기본값
+## 핵심 규칙 (스택 무관)
+
+- api-contract.json 이 있으면 그에 정의된 엔드포인트만 호출/매핑
+- 로딩·에러·빈 상태 3가지 필수 처리 (UI 가 있는 스택에서)
+- 접근성·키보드 네비게이션 기본 고려 (ref.validation.visual 설정에 따름)
+- 로케일·i18n 은 ref-docs 본문 가이드 준수
 
 ## 금지 사항
 
-- Backend 코드 수정, Gateway 내부 서비스 직접 호출
-- api-contract.json에 없는 엔드포인트 호출
-- AI Forbidden Patterns 목록의 모든 항목
-- `h-screen` 사용 (`min-h-[100dvh]`로 대체)
-- `window.addEventListener('scroll')` (IntersectionObserver 사용)
-- `linear` / `ease-in-out` 트랜지션 (커스텀 cubic-bezier 사용)
+- **ref.paths.source_roots 밖의 프로덕션 코드 수정** (BE/HARNESS 영역 침범 금지)
+- api-contract.json 에 없는 엔드포인트 호출 (base_url 이 있는 경우)
+- `.harness/ref/` 직접 편집 (refresh 는 `bash init.sh refresh-ref` 경유)
+- 공통 `generator-frontend.md` / 스택별 `generator-frontend-<stack>.md` gotcha 에 적힌 실수 반복
+
+## 디버깅 / Fallback
+
+- `ref-docs` 가 placeholder 상태(`generator: "init-ref-docs.sh (placeholder)"`) → 본격 구현 전에 Claude 세션에서 `bash init.sh refresh-ref fe <stack>` 후 프롬프트 실행으로 본문 채우기를 권고
+- `scan-result.json.tech_stack_confidence == "unknown"` → 사용자에게 객관식(감지 후보 top 5 + 자유입력 fallback)으로 스택 확인 요청

package/skills/planner/SKILL.md

@@ -75,10 +75,58 @@ disable-model-invocation: true
 ## Constraints
 
 - 기술 구현 세부사항은 Generator에 위임
-- Sprint당 기능 3-5개 권장
 - 각 기능에 `layer`, `service`, `depends_on` 명시
 - API 계약의 스키마는 Pydantic/class-validator로 직접 변환 가능한 수준
 
+## Team 병렬 스케줄링 규칙 (필수)
+
+Team Mode는 **최대 3팀이 동시 작업**한다. Planner는 feature-list.json 설계 시 다음 규칙을 반드시 준수한다.
+
+### 핵심 원칙: Sprint 시작 시 ready ≥ 3
+
+Sprint 시작 시점에 `depends_on`이 모두 충족된(또는 비어 있는) feature가 **최소 3개** 있어야 3팀이 즉시 가동된다. ready가 1~2개이면 나머지 팀은 유휴 상태가 된다.
+
+### 의존성 그래프 형태
+
+**금지 — 직렬 체인:**
+```
+F-001 → F-002 → F-003 → F-004  (ready=1, 1팀만 작업)
+```
+
+**권장 — 넓은 DAG (fan-out):**
+```
+           ┌→ F-002 (no deps)
+Foundation → F-003 (no deps)      (ready=3, 3팀 동시)
+           └→ F-004 (no deps)
+                    ↓
+                  F-005 (depends_on: [F-002, F-003])
+```
+
+### Sprint 설계 체크리스트
+
+1. **Sprint당 feature 수**: `팀수 × 2` 이상 (3팀 = 최소 6개)
+   - 3개는 즉시 시작, 나머지는 앞선 feature 완료 시 투입
+   - 팀이 PASS 후 대기하지 않고 바로 다음 feature를 가져감
+2. **동시 ready 보장**: Sprint 내 feature 중 `depends_on: []`인 것이 ≥ 3개
+3. **의존성 깊이(critical path) 최소화**: 같은 Sprint 내 체인 깊이 ≤ 2단계
+4. **layer 분산**: 같은 Sprint에 backend-only, frontend-only, fullstack을 혼합하여 서로 독립적으로 작업 가능
+5. **Feature 분할**: 하나의 큰 feature 대신 독립 AC 그룹으로 분할
+   - 예: "대시보드 전체" (1개) → "통계 카드" + "차트 영역" + "최근 활동" (3개, 동시 작업 가능)
+
+### 검증: ready count 시뮬레이션
+
+feature-list.json 완성 후, Sprint별 ready count를 머릿속으로 시뮬레이션한다:
+
+```
+Sprint N 시작 → ready 목록 계산
+  ready ≥ 3  → OK (3팀 동시 가동)
+  ready = 2  → WARNING (1팀 유휴)
+  ready = 1  → FAIL → feature 분할 또는 의존성 제거 필요
+  ready = 0  → CRITICAL → 이전 Sprint 의존성 재설계 필요
+```
+
+ready가 3 미만인 Sprint가 있으면 **feature를 더 작게 분할하거나 의존성을 제거**하여 수정한다.
+
 ## After Completion
 
 1. 사용자에게 plan.md + api-contract.json 리뷰 요청