@walwal-harness/cli 5.1.0 → 5.3.0

package/commands/harness-team.md

@@ -1,3 +1,17 @@
+---
+docmeta:
+  id: harness-team
+  title: /harness-team — Team Mode 시작/재개
+  type: input
+  createdAt: 2026-04-20T00:00:00Z
+  updatedAt: 2026-04-20T00:00:00Z
+  source:
+    producer: user
+    skillId: harness
+  inputs: []
+  tags: [harness, team-mode, tmux, command]
+---
+
 # /harness-team — Team Mode 시작/재개
 
 Planner가 완료한 feature-list.json의 피처들을 최대 3개 팀이 병렬로 Gen→Eval 사이클을 수행합니다.
@@ -40,9 +54,11 @@ bash scripts/harness-queue-manager.sh status .
 ### Step 2: tmux Studio 레이아웃 구축
 
 ```bash
-bash scripts/harness-tmux.sh --team
+bash scripts/harness-tmux.sh --team --force-tmux
 ```
 
+**`--force-tmux` 필수**: iTerm2 감지 경로는 백그라운드에 iTerm2가 떠 있기만 해도 활성화되어 AppleScript 실패 시 팀 레이아웃이 조용히 사라짐. Team Mode는 항상 tmux로 강제하여 재현 가능한 레이아웃을 보장.
+
 ### Step 3: 초기 Worker 생성
 
 Queue에서 ready 피처를 최대 3개 dequeue하고, **각각 background Agent로 생성**합니다.
@@ -162,18 +178,28 @@ LOG="$HARNESS_ROOT/.harness/progress.log"
 logev() { echo "$(date +'%Y-%m-%d %H:%M') | team-{N} | $1 | $2" >> "$LOG"; }
 ```
 
-| ACTION | 사용 시점 | DETAIL 예시 |
-|--------|-----------|-------------|
-| `gen-start`  | Gen Phase 시작 | `F-001 start — 6 AC` |
-| `gen-read`   | 소스/계약 읽기 | `read api-contract.json (POST /users)` |
-| `gen-write`  | 파일 생성/수정 | `write apps/service-user/src/user.controller.ts` |
-| `gen-test`   | 자체 게이트 | `tsc OK · eslint 0 · jest 12/12` |
-| `gen-done`   | Gen Phase 종료 | `F-001 done — 5 files, 142 LOC` |
-| `eval-start` | Evaluator 시작 | `F-001 spawning evaluator` |
-| `eval-check` | AC 검증 | `AC-3 — verify POST /users returns 201` |
-| `eval-done`  | Eval 결과 | `verdict=PASS score=2.95` |
-| `result`     | PASS 확정 | `F-001 PASS` |
-| `fail`       | FAIL 확정 | `FAIL #1 — AC-2 missing` |
+| ACTION | 사용 시점 | DETAIL 예시 (필수 포함 정보) |
+|--------|-----------|------------------------------|
+| `gen-start`  | Gen Phase 시작 (1회) | `F-001 "사용자 회원가입 API" start — goal=POST /users, 6 AC` — **Feature 제목+목표** 포함 필수 |
+| `gen-plan`   | 작업 계획 공표 (1회) | `plan: create controller+service+dto, wire module, add 3 unit tests` |
+| `gen-read`   | 소스/계약 읽기 (매 파일) | `read api-contract.json#/paths/~1users` |
+| `gen-write`  | 파일 생성/수정 (**매 파일**) | `write apps/service-user/src/user.controller.ts (+82 LOC, create)` — **경로+LOC+action(create/edit/delete)** 필수 |
+| `gen-test`   | 자체 게이트 | `tsc OK · eslint 0 warn · jest 12/12 pass` |
+| `gen-done`   | Gen Phase 종료 | `F-001 done — 5 files: controller.ts, service.ts, dto.ts, module.ts, spec.ts (total +142 LOC)` — **변경 파일 전체 나열** 필수 |
+| `eval-start` | Evaluator 시작 | `F-001 evaluating — 6 ACs + regression + security` — **AC 개수+검증 축** 필수 |
+| `eval-ac`    | AC 본문 선언 (**매 AC 시작 시 1회**) | `AC-3: "POST /users returns 201 with created user id"` — **AC 원문** 필수 |
+| `eval-check` | AC 검증 수행/증거 | `AC-3 [PASS] — curl POST /users → 201, body.id matches` — **판정+증거** 필수 |
+| `eval-gate`  | 자동 게이트 | `gate: tsc OK, eslint OK, security scan 0 high` |
+| `eval-done`  | Eval 결과 | `F-001 VERDICT=PASS SCORE=2.95/3.00 (AC 6/6, gates OK)` |
+| `result`     | PASS 확정 (**SCORE ≥ 2.80**) | `F-001 PASS score=2.95` |
+| `fail`       | FAIL 확정 | `F-001 FAIL #1 — AC-2 "email uniqueness" missing DB constraint` |
+
+**중요: 로깅 가독성 규칙 (필수)**
+1. `gen-start`에는 반드시 Feature **제목과 목표**를 함께 기록 (무슨 일을 시작하는가 명확히).
+2. `gen-write`는 **변경되는 파일마다 1건씩** 기록. 묶어서 요약 금지 ("2 files edit" 같은 표기 금지).
+3. `gen-done`은 **변경 파일 전체 목록**을 나열. "(2 files)" 같은 개수만 기록 금지.
+4. `eval-ac`로 **AC 원문을 먼저 선언**한 뒤 `eval-check`로 증거/판정 기록. "AC-1 count=0" 같은 수치 단독 기록 금지.
+5. `result` PASS는 **SCORE ≥ 2.80** 인 경우에만 기록. score=1.00인데 PASS로 기록하는 실수 금지.
 
 **queue phase 업데이트:**
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@walwal-harness/cli",
-  "version": "5.1.0",
+  "version": "5.3.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-gotcha-memory.sh

@@ -0,0 +1,165 @@
+#!/bin/bash
+# harness-gotcha-memory.sh — Gotcha & Memory pane (index view)
+# 활성 에이전트의 gotcha를 최상단으로, 나머지는 요약(최근 3항목+총개수)으로 표시
+# Usage: bash scripts/harness-gotcha-memory.sh [project-root]
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+source "$SCRIPT_DIR/lib/harness-render-progress.sh"
+
+PROJECT_ROOT="${1:-}"
+if [ -z "$PROJECT_ROOT" ]; then
+  PROJECT_ROOT="$(resolve_harness_root ".")" || { echo "[gotcha] .harness/ not found."; exit 1; }
+fi
+
+MEMORY_FILE="$PROJECT_ROOT/.harness/memory.md"
+GOTCHAS_DIR="$PROJECT_ROOT/.harness/gotchas"
+PROGRESS="$PROJECT_ROOT/.harness/progress.json"
+
+BOLD="\033[1m"
+DIM="\033[2m"
+GREEN="\033[32m"
+YELLOW="\033[33m"
+RED="\033[31m"
+CYAN="\033[36m"
+MAGENTA="\033[35m"
+RESET="\033[0m"
+BG_YELLOW="\033[43m"
+
+REFRESH_SEC="${HARNESS_REFRESH:-5}"
+RECENT_N="${HARNESS_GOTCHA_RECENT:-3}"
+
+# 활성 에이전트 결정: current_agent > next_agent
+get_active_agent() {
+  [ -f "$PROGRESS" ] || { echo ""; return; }
+  command -v jq &>/dev/null || { echo ""; return; }
+  local cur nxt
+  cur=$(jq -r '.current_agent // ""' "$PROGRESS" 2>/dev/null)
+  nxt=$(jq -r '.next_agent // ""' "$PROGRESS" 2>/dev/null)
+  if [ -n "$cur" ] && [ "$cur" != "null" ] && [ "$cur" != "none" ]; then
+    echo "$cur"
+  elif [ -n "$nxt" ] && [ "$nxt" != "null" ] && [ "$nxt" != "none" ]; then
+    echo "$nxt"
+  else
+    echo ""
+  fi
+}
+
+# gotcha 파일에서 '### ' 헤딩 개수 = 항목 총수
+count_items() {
+  local f="$1"
+  local n
+  n=$(grep -c '^### ' "$f" 2>/dev/null)
+  echo "${n:-0}"
+}
+
+# 최근 N개 항목 제목 추출 (### 헤딩 — 파일 하단부가 최신이라 tail)
+recent_titles() {
+  local f="$1" n="$2"
+  grep '^### ' "$f" 2>/dev/null | tail -n "$n" | sed 's/^### //'
+}
+
+# agent 이름 → 파일 basename 매핑 (정확/접두 일치)
+file_for_agent() {
+  local agent="$1"
+  local f="$GOTCHAS_DIR/${agent}.md"
+  [ -f "$f" ] && { echo "$f"; return; }
+  # 접두 일치 (예: current_agent=generator → generator-backend/frontend 중 하나)
+  for cand in "$GOTCHAS_DIR"/*.md; do
+    [ -e "$cand" ] || continue
+    local base
+    base=$(basename "$cand" .md)
+    [ "$base" = "README" ] && continue
+    case "$base" in
+      "$agent"*|*"$agent"*) echo "$cand"; return ;;
+    esac
+  done
+  echo ""
+}
+
+render_gotcha_entry() {
+  local f="$1" active="$2"
+  local name count
+  name=$(basename "$f" .md)
+  count=$(count_items "$f")
+  if [ "$active" = "true" ]; then
+    echo -e "${BOLD}${BG_YELLOW} ▸ ${name} ${RESET} ${DIM}(${count} items · ACTIVE)${RESET}"
+  else
+    echo -e "${BOLD}${GREEN}▸ ${name}${RESET} ${DIM}(${count} items)${RESET}"
+  fi
+  if [ "$count" -eq 0 ]; then
+    echo -e "  ${DIM}(항목 없음)${RESET}"
+  else
+    recent_titles "$f" "$RECENT_N" | while IFS= read -r t; do
+      echo -e "  ${DIM}·${RESET} $t"
+    done
+  fi
+}
+
+render_memory_summary() {
+  if [ ! -f "$MEMORY_FILE" ]; then
+    echo -e "${DIM}(memory.md 없음)${RESET}"
+    return
+  fi
+  local count
+  count=$(grep -c '^### ' "$MEMORY_FILE" 2>/dev/null)
+  count="${count:-0}"
+  echo -e "${BOLD}${CYAN}▣ SHARED MEMORY${RESET} ${DIM}(${count} items · memory.md)${RESET}"
+  if [ "$count" -eq 0 ]; then
+    echo -e "  ${DIM}(항목 없음)${RESET}"
+  else
+    grep '^### ' "$MEMORY_FILE" | tail -n "$RECENT_N" | sed 's/^### //' | while IFS= read -r t; do
+      echo -e "  ${DIM}·${RESET} $t"
+    done
+  fi
+}
+
+render() {
+  clear
+  local cols hr
+  cols=$(tput cols 2>/dev/null || echo 80)
+  hr=$(printf '─%.0s' $(seq 1 "$cols"))
+
+  local active active_file
+  active=$(get_active_agent)
+  active_file=""
+  [ -n "$active" ] && active_file=$(file_for_agent "$active")
+
+  echo -e "${BOLD}${MAGENTA}GOTCHA INDEX${RESET}  ${DIM}$(date +%H:%M:%S) · recent=${RECENT_N} · refresh ${REFRESH_SEC}s${RESET}"
+  if [ -n "$active" ]; then
+    echo -e "${DIM}active agent:${RESET} ${BOLD}${YELLOW}${active}${RESET}"
+  else
+    echo -e "${DIM}active agent: (none)${RESET}"
+  fi
+  echo -e "${DIM}${hr}${RESET}"
+
+  # 활성 에이전트 gotcha 최상단
+  if [ -n "$active_file" ]; then
+    render_gotcha_entry "$active_file" "true"
+    echo ""
+  fi
+
+  # 나머지 gotcha
+  if [ -d "$GOTCHAS_DIR" ]; then
+    for f in "$GOTCHAS_DIR"/*.md; do
+      [ -e "$f" ] || continue
+      [ "$f" = "$active_file" ] && continue
+      local base
+      base=$(basename "$f" .md)
+      [ "$base" = "README" ] && continue
+      render_gotcha_entry "$f" "false"
+    done
+  fi
+
+  echo ""
+  echo -e "${DIM}${hr}${RESET}"
+  render_memory_summary
+}
+
+trap 'exit 0' INT TERM
+
+while true; do
+  render
+  sleep "$REFRESH_SEC"
+done

package/scripts/harness-tmux.sh

@@ -4,10 +4,10 @@
 # Team Mode (--team):
 # ┌──────────────┬──────────────┬──────────────┐
 # │              │              │   TEAM 1     │
-# │  Prompt      │  Dashboard   │  Gen | Eval   │
-# │  History     │  (queue +    ├──────────────┤
-# │              │   status +   │   TEAM 2     │
-# │              │   archive)   │  Gen | Eval   │
+# │  Dashboard   │  Gotcha &    │              │
+# │  (queue +    │  Memory      ├──────────────┤
+# │   status +   │              │   TEAM 2     │
+# │   archive)   │              │              │
 # │              │              ├──────────────┤
 # │              │              │   TEAM 3     │
 # └──────────────┴──────────────┴──────────────┘
@@ -20,6 +20,7 @@
 # Usage:
 #   bash scripts/harness-tmux.sh [project-root] --team
 #   bash scripts/harness-tmux.sh [project-root] --solo
+#   bash scripts/harness-tmux.sh [project-root] --team --force-tmux  # skip iTerm2, use tmux
 #   bash scripts/harness-tmux.sh --kill
 
 set -euo pipefail
@@ -30,12 +31,14 @@ SESSION_NAME="harness-studio"
 PROJECT_ROOT=""
 MODE=""
 DETACH=false
+FORCE_TMUX=false
 
 for arg in "$@"; do
   case "$arg" in
     --team)   MODE="team" ;;
     --solo)   MODE="solo" ;;
     --detach) DETACH=true ;;
+    --force-tmux) FORCE_TMUX=true ;;
     --kill)
       tmux kill-session -t "$SESSION_NAME" 2>/dev/null && echo "tmux session killed." || true
       # Also try to close iTerm2 studio tab if exists
@@ -99,12 +102,12 @@ launch_iterm2_team() {
       tell studioWindow
         tell current session of current tab
           set name to "harness-studio"
-          write text "cd '${PROJECT_ROOT}' && bash '${SCRIPT_DIR}/harness-prompt-history.sh' '${PROJECT_ROOT}'"
+          write text "cd '${PROJECT_ROOT}' && bash '${SCRIPT_DIR}/harness-dashboard.sh' '${PROJECT_ROOT}'"
 
-          -- Split right → Dashboard
+          -- Split right → Gotcha & Memory
           set dashPane to (split vertically with default profile)
           tell dashPane
-            write text "cd '${PROJECT_ROOT}' && bash '${SCRIPT_DIR}/harness-dashboard.sh' '${PROJECT_ROOT}'"
+            write text "cd '${PROJECT_ROOT}' && bash '${SCRIPT_DIR}/harness-gotcha-memory.sh' '${PROJECT_ROOT}'"
 
             -- Split right → Team 1
             set t1Pane to (split vertically with default profile)
@@ -171,24 +174,24 @@ APPLESCRIPT
 launch_tmux_team() {
   tmux kill-session -t "$SESSION_NAME" 2>/dev/null || true
 
-  PANE_LEFT=$(tmux new-session -d -s "$SESSION_NAME" -c "$PROJECT_ROOT" -x 220 -y 55 -P -F '#{pane_id}')
-  PANE_MID=$(tmux split-window -h -p 70 -t "$PANE_LEFT" -c "$PROJECT_ROOT" -P -F '#{pane_id}')
-  PANE_T1=$(tmux split-window -h -p 60 -t "$PANE_MID" -c "$PROJECT_ROOT" -P -F '#{pane_id}' \
+  PANE_DASH=$(tmux new-session -d -s "$SESSION_NAME" -c "$PROJECT_ROOT" -x 220 -y 55 -P -F '#{pane_id}')
+  PANE_GOTCHA=$(tmux split-window -h -p 70 -t "$PANE_DASH" -c "$PROJECT_ROOT" -P -F '#{pane_id}')
+  PANE_T1=$(tmux split-window -h -p 60 -t "$PANE_GOTCHA" -c "$PROJECT_ROOT" -P -F '#{pane_id}' \
     "bash --norc --noprofile -c 'exec bash \"${SCRIPT_DIR}/harness-monitor.sh\" \"${PROJECT_ROOT}\" --team 1'")
   PANE_T2=$(tmux split-window -v -p 66 -t "$PANE_T1" -c "$PROJECT_ROOT" -P -F '#{pane_id}' \
     "bash --norc --noprofile -c 'exec bash \"${SCRIPT_DIR}/harness-monitor.sh\" \"${PROJECT_ROOT}\" --team 2'")
   PANE_T3=$(tmux split-window -v -p 50 -t "$PANE_T2" -c "$PROJECT_ROOT" -P -F '#{pane_id}' \
     "bash --norc --noprofile -c 'exec bash \"${SCRIPT_DIR}/harness-monitor.sh\" \"${PROJECT_ROOT}\" --team 3'")
 
-  tmux send-keys -t "$PANE_LEFT" "bash \"${SCRIPT_DIR}/harness-prompt-history.sh\" \"${PROJECT_ROOT}\"" Enter
-  tmux send-keys -t "$PANE_MID" "bash \"${SCRIPT_DIR}/harness-dashboard.sh\" \"${PROJECT_ROOT}\"" Enter
+  tmux send-keys -t "$PANE_DASH"   "bash \"${SCRIPT_DIR}/harness-dashboard.sh\" \"${PROJECT_ROOT}\"" Enter
+  tmux send-keys -t "$PANE_GOTCHA" "bash \"${SCRIPT_DIR}/harness-gotcha-memory.sh\" \"${PROJECT_ROOT}\"" Enter
 
-  tmux select-pane -t "$PANE_LEFT"  -T "Prompt History"
-  tmux select-pane -t "$PANE_MID"   -T "Dashboard"
-  tmux select-pane -t "$PANE_T1"    -T "TEAM 1"
-  tmux select-pane -t "$PANE_T2"    -T "TEAM 2"
-  tmux select-pane -t "$PANE_T3"    -T "TEAM 3"
-  tmux select-pane -t "$PANE_LEFT"
+  tmux select-pane -t "$PANE_DASH"   -T "Dashboard"
+  tmux select-pane -t "$PANE_GOTCHA" -T "Gotcha & Memory"
+  tmux select-pane -t "$PANE_T1"     -T "TEAM 1"
+  tmux select-pane -t "$PANE_T2"     -T "TEAM 2"
+  tmux select-pane -t "$PANE_T3"     -T "TEAM 3"
+  tmux select-pane -t "$PANE_DASH"
 
   tmux set-option -t "$SESSION_NAME" pane-border-status top 2>/dev/null || true
   tmux set-option -t "$SESSION_NAME" pane-border-format " #{pane_title} " 2>/dev/null || true
@@ -237,6 +240,15 @@ if command -v tmux &>/dev/null; then
   HAS_TMUX=true
 fi
 
+# --force-tmux overrides iTerm2 detection
+if [ "$FORCE_TMUX" = true ]; then
+  if [ "$HAS_TMUX" != true ]; then
+    echo "ERROR: --force-tmux specified but tmux not installed. Run: brew install tmux"
+    exit 1
+  fi
+  IS_ITERM=false
+fi
+
 if [ "$IS_ITERM" = true ]; then
   echo "Strategy: iTerm2 native split panes"
   if [ "$MODE" = "team" ]; then

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)으로 스택 확인 요청