@walwal-harness/cli 5.6.3 → 5.6.5

package/README.md

@@ -83,11 +83,34 @@ npx walwal-harness team
 
 | 패널 | 내용 | 소스 |
 |------|------|------|
-| **Dashboard** | Pipeline · Sprint · Feature passes (●/◐/○/◌/✗) · Queue R:B:P · Retry | `harness-dashboard.sh` |
+| **Dashboard** | Pipeline · Sprint · Feature passes · Queue R:B:P · Retry | `harness-dashboard.sh` |
 | **Gotcha & Memory** | 활성 에이전트의 누적 실수 + 나머지 요약 + 공유 메모리 | `harness-gotcha-memory.sh` |
 | **TEAM 1–3** | 각 워커의 현재 feature · phase(Gen/Eval) · 실시간 stdout | `harness-queue-manager.sh` worker loop |
 | **Archive Prompt** | 직전 완료 feature 요약 (다음 팀 컨텍스트 주입용) | archive 디렉토리 |
 
+##### Feature 상태 아이콘 (v5.6.4+)
+
+| 아이콘 | 상태 | 의미 |
+|--------|------|------|
+| `●` (녹색) | PASS | Evaluator 통과 · merge 완료 |
+| `◐` (청색) | IN PROGRESS | 현재 team 배정됨 (phase 표기: T1:gen / T2:eval) |
+| `○` (노랑) | READY | 의존성 해소됨 · idle team 배정 대기 |
+| `◍` (자색) | **BLOCKED** | 선행 feature 대기 · deps 개수 함께 표시 |
+| `◌` (어두움) | PENDING | 아직 큐 미등록 (sprint 미진입 or 사전 분석 단계) |
+| `✗` (빨강) | FAILED | 재시도 한도 도달 · 사용자 개입 필요 |
+
+##### Team Idle Auto-Dispatch (v5.6.4+)
+
+Worker 완료 시 Lead 는 `auto-dispatch` 한 호출로 **모든 idle team ↔ ready feature** 쌍을 원자적으로 재배정합니다. 의존성 없는 작업은 병렬로 즉시 시작되어 team idle 시간은 "Agent 생성 소요 초" 로 수렴:
+
+```bash
+bash scripts/harness-queue-manager.sh auto-dispatch .
+# → [{"team":1,"feature":"F-001"},{"team":2,"feature":"F-002"}]
+
+bash scripts/harness-queue-manager.sh idle-slots .
+# → {"idle_teams":["3"], "ready_features":["F-003","F-004"], "dispatchable":1}
+```
+
 - 새로고침 주기: `HARNESS_REFRESH=5` (초). 환경변수로 조정.
 - 단축키: `tmux prefix + 방향키` 로 패널 이동, `prefix + z` 로 확대/축소.
 - 종료: `npx walwal-harness team --kill`.

package/commands/harness-team.md

@@ -59,17 +59,20 @@ bash scripts/harness-tmux.sh --team --force-tmux
 
 **`--force-tmux` 필수**: iTerm2 감지 경로는 백그라운드에 iTerm2가 떠 있기만 해도 활성화되어 AppleScript 실패 시 팀 레이아웃이 조용히 사라짐. Team Mode는 항상 tmux로 강제하여 재현 가능한 레이아웃을 보장.
 
-### Step 3: 초기 Worker 생성
+### Step 3: 초기 Worker 생성 (Auto-Dispatch)
 
-Queue에서 ready 피처를 최대 3개 dequeue하고, **각각 background Agent로 생성**합니다.
+**v5.6.4+**: 개별 dequeue 대신 **`auto-dispatch`** 한 번으로 모든 idle team 에 ready feature 를 원자적으로 배정합니다. 의존성 없는 작업은 병렬로 즉시 시작됩니다.
 
 ```bash
-# 각 팀마다 dequeue
-bash scripts/harness-queue-manager.sh dequeue 1 .
-bash scripts/harness-queue-manager.sh dequeue 2 .
-bash scripts/harness-queue-manager.sh dequeue 3 .
+# 모든 idle team ↔ ready feature 쌍을 한 번에 배정
+bash scripts/harness-queue-manager.sh auto-dispatch .
+# → [{"team":1,"feature":"F-001"},{"team":2,"feature":"F-002"},{"team":3,"feature":"F-003"}]
 ```
 
+출력(JSON 배열)을 파싱해 각 `{team, feature}` 쌍마다 **background Agent** 를 생성합니다.
+
+> **Fallback**: 단일 팀만 배정하려면 `dequeue <team_id>` 도 계속 사용 가능.
+
 dequeue 성공한 피처마다 **background Agent**를 생성합니다:
 
 ```
@@ -99,25 +102,29 @@ ORCHESTRATION LOOP:
      - FAIL (재시도 가능)인 경우 → Step 4b (Retry)
      - ESCALATED인 경우 → 사용자에게 알림, 해당 팀 유휴
 
-  2. Queue 상태 확인:
-     bash scripts/harness-queue-manager.sh status .
+  2. **Auto-Dispatch (필수)** — worker 완료 직후 idle 이 된 팀뿐 아니라
+     모든 idle team 에 ready feature 를 즉시 재배정:
 
-  3. ready > 0 이면:
-     → 새 Worker를 background Agent로 생성 (Step 3과 동일)
-     → LOOP 계속
+     bash scripts/harness-queue-manager.sh auto-dispatch .
 
-  4. ready = 0 AND in_progress > 0 이면:
-     → 다른 Worker 완료를 대기
-     → LOOP 계속
+     반환된 모든 (team, feature) 쌍에 대해 즉시 background Agent 생성.
+     한 작업의 merge 지연이 다른 idle team 을 놀게 두지 않는다.
 
-  5. ready = 0 AND in_progress = 0 이면:
-     → Sprint 전환 시도:
+  3. Queue 상태 확인 (로그용):
+     bash scripts/harness-queue-manager.sh idle-slots .
+     bash scripts/harness-queue-manager.sh status .
+
+  4. auto-dispatch 가 pairs=[] (= ready 도 0, idle 도 0 혹은 idle 만 있고 ready 가 0) 이면:
+     → ready=0 AND in_progress>0 → 다른 worker 완료 대기. LOOP 계속
+     → ready=0 AND in_progress=0 → Sprint 전환 시도:
        bash scripts/harness-queue-manager.sh next-sprint .
-       - "Advancing" → Step 3으로 (새 Sprint 피처 dequeue + Worker 생성)
+       - "Advancing" → auto-dispatch 다시 실행 (Step 2로 복귀)
        - "ALL SPRINTS COMPLETE" → 최종 보고. LOOP 종료.
        - "Cannot advance" → 실패 피처 사용자 개입 요청. LOOP 종료.
 ```
 
+**핵심 원칙**: worker 완료 알림 → **즉시 auto-dispatch** → 반환된 모든 쌍에 대해 병렬 spawn. 팀 간 의존성이 없으면 idle 시간은 "Agent 생성에 걸리는 수초" 로 수렴한다.
+
 #### Step 4a: Merge + Unblock (PASS 처리)
 
 Worker가 PASS로 반환되면:

package/package.json

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

package/scripts/harness-dashboard.sh

@@ -269,6 +269,7 @@ render_team_features() {
     ($q[0].queue.failed // []) as $failed |
     ($q[0].queue.ready // []) as $ready |
     ($q[0].queue.in_progress // {}) as $prog |
+    ($q[0].queue.blocked // {}) as $blocked |
     .features[] |
     .id as $fid |
     (.name // .title // .description // "?" | if length > 18 then .[0:16] + ".." else . end) as $fname |
@@ -276,18 +277,21 @@ render_team_features() {
      elif $prog[$fid] then "I|\($prog[$fid].team)|\($prog[$fid].phase)"
      elif ($fid | IN($failed[])) then "F"
      elif ($fid | IN($ready[])) then "R"
-     else "B" end) as $st |
+     elif $blocked[$fid] then "BLK|\($blocked[$fid] | length)"
+     else "U" end) as $st |
     "\($st)\t\($fid)\t\($fname)"
   ' "$FEATURES" 2>/dev/null | while IFS=$'\t' read -r st fid fname; do
     case "$st" in
-      P)    printf "  ${GREEN}●${RESET} %-6s %s\n" "$fid" "$fname" ;;
-      F)    printf "  ${RED}✗${RESET} %-6s %s\n" "$fid" "$fname" ;;
-      R)    printf "  ${YELLOW}○${RESET} %-6s %s\n" "$fid" "$fname" ;;
-      B)    printf "  ${DIM}◌${RESET} %-6s %s\n" "$fid" "$fname" ;;
-      I\|*) team=$(echo "$st" | cut -d'|' -f2)
-            phase=$(echo "$st" | cut -d'|' -f3)
-            printf "  ${CYAN}◐${RESET} %-6s %-14s T%s:%s\n" "$fid" "$fname" "$team" "$phase" ;;
-      *)    printf "  ? %-6s %s\n" "$fid" "$fname" ;;
+      P)      printf "  ${GREEN}●${RESET} %-6s %s\n" "$fid" "$fname" ;;
+      F)      printf "  ${RED}✗${RESET} %-6s %s\n" "$fid" "$fname" ;;
+      R)      printf "  ${YELLOW}○${RESET} %-6s %s\n" "$fid" "$fname" ;;
+      BLK\|*) deps=$(echo "$st" | cut -d'|' -f2)
+              printf "  ${MAGENTA}◍${RESET} %-6s %-22s ${DIM}blocked (deps:%s)${RESET}\n" "$fid" "$fname" "$deps" ;;
+      U)      printf "  ${DIM}◌${RESET} %-6s %s\n" "$fid" "$fname" ;;
+      I\|*)   team=$(echo "$st" | cut -d'|' -f2)
+              phase=$(echo "$st" | cut -d'|' -f3)
+              printf "  ${CYAN}◐${RESET} %-6s %-22s T%s:%s\n" "$fid" "$fname" "$team" "$phase" ;;
+      *)      printf "  ? %-6s %s\n" "$fid" "$fname" ;;
     esac
   done
 }

package/scripts/harness-next.sh

@@ -54,7 +54,7 @@ if [ -f "$PIPELINE_JSON" ]; then
   fe_target=$(jq -r '.fe_target // empty' "$PIPELINE_JSON" 2>/dev/null || true)
   if [ -z "$fe_target" ]; then
     # pipeline.json 에 fe_target 미지정 시 config.json 의 _default_target 사용
-    fe_target=$(jq -r ".flow.pipeline_selection.fe_stack_substitution.${fe_stack}._default_target // \"web\"" "$CONFIG" 2>/dev/null || echo "web")
+    fe_target="web"  # v5.6.5+: 치환 로직 제거. fe_target 은 pipeline.json 에서 명시하거나 web 기본.
   fi
 fi
 

package/scripts/harness-queue-manager.sh

@@ -424,19 +424,84 @@ cmd_recover() {
   echo "[queue] Recovered ${stale_count} stale features back to ready queue."
 }
 
+# ══════════════════════════════════════════
+# auto-dispatch — Pair all idle teams with ready features in one atomic step.
+#   Output: JSON array of {team, feature} on stdout.
+#   Atomically moves ready → in_progress + teams[tid] = busy for each pair.
+#   Dependencies are already honored (ready queue only holds unblocked features).
+# ══════════════════════════════════════════
+cmd_auto_dispatch() {
+  if [ ! -f "$QUEUE" ]; then echo "[queue] Run 'init' first." >&2; exit 1; fi
+
+  acquire_queue_lock
+
+  local result
+  result=$(jq '
+    . as $root |
+    ($root.teams | to_entries | map(select(.value.status == "idle")) | map(.key)) as $idle |
+    ($root.queue.ready) as $ready |
+    (if ($idle | length) < ($ready | length) then ($idle | length) else ($ready | length) end) as $n |
+    [range(0; $n) | { team: ($idle[.] | tonumber), feature: $ready[.] }] as $pairs |
+    (reduce $pairs[] as $p ($root;
+      .queue.ready -= [$p.feature] |
+      .queue.in_progress[$p.feature] = { team: $p.team, phase: "gen", attempt: 1 } |
+      .teams[($p.team | tostring)] = {
+        status: "busy",
+        feature: $p.feature,
+        branch: ("feature/" + $p.feature),
+        pid: null
+      }
+    )) as $updated |
+    { state: $updated, pairs: $pairs }
+  ' "$QUEUE")
+
+  local new_state pairs
+  new_state=$(echo "$result" | jq '.state')
+  pairs=$(echo "$result" | jq -c '.pairs')
+
+  # Write updated state
+  echo "$new_state" > "${QUEUE}.tmp" && mv "${QUEUE}.tmp" "$QUEUE"
+
+  release_queue_lock
+
+  # Emit pairs (single JSON line) for caller
+  echo "$pairs"
+}
+
+# ══════════════════════════════════════════
+# idle-slots — Report how many teams are idle + how many ready features wait.
+#   No state mutation. Useful for dashboards / quick checks.
+# ══════════════════════════════════════════
+cmd_idle_slots() {
+  if [ ! -f "$QUEUE" ]; then echo "[queue] Run 'init' first." >&2; exit 1; fi
+  jq '{
+    idle_teams: [.teams | to_entries[] | select(.value.status == "idle") | .key],
+    ready_features: .queue.ready,
+    dispatchable: (
+      (if ([.teams | to_entries[] | select(.value.status == "idle") | .key] | length) <
+          (.queue.ready | length)
+        then [.teams | to_entries[] | select(.value.status == "idle") | .key] | length
+        else .queue.ready | length
+      end)
+    )
+  }' "$QUEUE"
+}
+
 # ── Dispatch ──
 case "$CMD" in
-  init)          cmd_init "$@" ;;
-  dequeue)       cmd_dequeue "$@" ;;
-  pass)          cmd_pass "$@" ;;
-  fail)          cmd_fail "$@" ;;
-  requeue)       cmd_requeue "$@" ;;
-  update_phase)  cmd_update_phase "$@" ;;
-  recover)       cmd_recover ;;
-  next-sprint)   cmd_next_sprint ;;
-  status)        cmd_status ;;
+  init)           cmd_init "$@" ;;
+  dequeue)        cmd_dequeue "$@" ;;
+  auto-dispatch)  cmd_auto_dispatch ;;
+  idle-slots)     cmd_idle_slots ;;
+  pass)           cmd_pass "$@" ;;
+  fail)           cmd_fail "$@" ;;
+  requeue)        cmd_requeue "$@" ;;
+  update_phase)   cmd_update_phase "$@" ;;
+  recover)        cmd_recover ;;
+  next-sprint)    cmd_next_sprint ;;
+  status)         cmd_status ;;
   *)
-    echo "Usage: harness-queue-manager.sh <init|dequeue|pass|fail|requeue|recover|next-sprint|update_phase|status> [args]"
+    echo "Usage: harness-queue-manager.sh <init|dequeue|auto-dispatch|idle-slots|pass|fail|requeue|recover|next-sprint|update_phase|status> [args]"
     exit 1
     ;;
 esac

package/scripts/lib/harness-guardrail.sh

@@ -29,9 +29,10 @@ get_allowed_paths() {
       echo "tsconfig"
       echo "docker-compose"
       ;;
-    generator-frontend|generator-frontend-flutter)
+    generator-frontend)
       echo "apps/web/"
       echo "apps/flutter/"
+      echo "lib/"
       echo ".harness/actions/sprint-contract.md"
       echo ".harness/actions/feature-list.json"
       echo ".harness/progress.json"
@@ -43,7 +44,7 @@ get_allowed_paths() {
       echo ".harness/actions/evaluation-code-quality.md"
       echo ".harness/progress.json"
       ;;
-    evaluator-functional|evaluator-functional-flutter)
+    evaluator-functional)
       echo ".harness/actions/evaluation-functional.md"
       echo ".harness/progress.json"
       echo "tests/"

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

@@ -311,7 +311,7 @@ render_agent_bar() {
     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")
+      fe_target="web"  # v5.6.5+: 치환 로직 제거. 기본 web.
     fi
   fi
 
@@ -325,14 +325,7 @@ render_agent_bar() {
 
   while IFS= read -r agent; do
     agent=$(echo "$agent" | sed 's/:.*//')  # strip mode suffix like :light, :api-only
-
-    # fe_stack + fe_target 치환 적용
-    if [ "$fe_stack" = "flutter" ]; then
-      local sub
-      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
+    # v5.6.5+: fe_stack 에이전트 치환 제거. 스택별 동작은 ref-docs 로 조절.
 
     if [ "$first" = true ]; then
       first=false

package/skills/dispatcher/SKILL.md

@@ -147,7 +147,7 @@ AGENTS.md 비하네스  → 기존 백업 + 리빌드
 - FULLSTACK / FE-ONLY: `["evaluator-code-quality", "evaluator-functional", "evaluator-visual"]`
 - BE-ONLY: `["evaluator-code-quality", "evaluator-functional"]` (functional 은 api-only 모드)
 
-Flutter 치환 규칙은 chain 배열의 각 원소에도 동일 적용. `fe_stack == "flutter"` + `fe_target in (mobile, desktop)` 이면 `evaluator-visual` 을 chain 에서 제거하고 `evaluator-functional` → `evaluator-functional-flutter` 로 치환한다. `evaluator-code-quality` 는 스택/타겟 무관 공통.
+스택 특성(예: Flutter mobile 에서 Visual skip) 이 필요하면 해당 스택 ref-docs (`.harness/ref/fe-<stack>.md`) 의 `validation.visual.enabled` 를 false 로 두면 evaluator-visual 이 MANUAL_REQUIRED 로 우아하게 우회한다. 별도 치환 에이전트는 사용하지 않는다.
 
 ### Evaluator 체인 라우팅 규칙
 
@@ -163,11 +163,9 @@ Gotcha retry 시에도 체인 시작점은 chain[0] 부터 재실행.
 
 FE-ONLY 또는 FULLSTACK 선택 시, `pipeline.json`에 **`fe_stack`** 필드를 포함해야 한다:
 
-- `scan-result.json.tech_stack.fe_stack` 값을 기본으로 사용 (`react` | `flutter`)
+- `scan-result.json.tech_stack.fe_stack` 값을 기본으로 사용 (예: `react`, `nextjs`, `vue`, `flutter`, `swift` 등)
 - 값이 없거나 불명확하면 Planner가 확정하도록 위임 (Dispatcher는 `"unknown"` 기록 + `notes` 에 메모)
-- Flutter 선택 시 `agents_active`/`agents_skipped`에 치환된 에이전트명을 기록
-  - active: `generator-frontend-flutter`, `evaluator-functional-flutter`
-  - skipped: `generator-frontend`, `evaluator-functional`, `evaluator-visual`
+- **에이전트 이름 치환은 하지 않는다** (v5.6.5+). 모든 FE 스택은 공통 `generator-frontend` / `evaluator-functional` / `evaluator-visual` 을 사용하고, 스택 특성은 `.harness/ref/fe-<stack>.md` (adaptive ref-docs) 에서 로드한다.
 
 ## 6. Brainstormer Routing Decision
 
@@ -222,7 +220,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` 또는 현재 에이전트 |
@@ -240,14 +238,8 @@ Planner 를 호출해야 한다고 판단되면, **사용자에게 단 하나의
 이 경우 기존 `.harness/actions/brainstorm-spec.md` 는 Brainstormer 의 On Start 에서
 `.harness/archive/brainstorm-spec-<timestamp>.md` 로 백업된다.
 
-## 7. Handoff 라우팅 (fe_stack 반영)
+## 7. Handoff 라우팅
 
-Dispatcher가 `next_agent` 를 세팅할 때 pipeline.json.fe_stack 을 참조해 치환:
+Dispatcher 가 `next_agent` 를 세팅할 때 **스택별 에이전트 이름 치환은 하지 않는다** (v5.6.5+). 모든 FE 스택이 공통 `generator-frontend` / `evaluator-functional` / `evaluator-visual` 을 사용하고, 스택 특성은 adaptive ref-docs(`.harness/ref/fe-<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 → 다음 단계로 이동) |
-
-**Brainstormer 는 fe_stack 치환 대상이 아니다** — 언어/스택 무관 공통 에이전트.
+예외적 스킵 규칙은 ref-docs 의 `validation.visual.enabled` 플래그로 제어 — false 면 evaluator-visual 이 MANUAL_REQUIRED 로 우아하게 우회한다 (별도 에이전트 이름 변경 없음).

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

@@ -28,35 +28,19 @@ docmeta:
 
 # Pipeline Definitions
 
-> **FE Stack 차원**: 모든 FE 관련 파이프라인은 `fe_stack` 필드로 React/Flutter를 구분한다.
+> **FE Stack 차원**: 모든 FE 관련 파이프라인은 `fe_stack` 필드로 스택을 기록한다.
 > Planner가 scan-result.json(`tech_stack.fe_stack`) 또는 사용자 질문으로 확정한다.
 
-## fe_stack + fe_target 스위치 매트릭스
+## 단일 에이전트 체인 (v5.6.5+)
 
-| 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** |
+**에이전트 이름 치환은 하지 않는다**. 모든 FE 스택(React, Next.js, Vue, Svelte, Flutter, Swift, 기타) 은 공통 `generator-frontend` / `evaluator-functional` / `evaluator-visual` 을 사용하며, 스택 특성(runner, paths, API, validation) 은 **adaptive ref-docs** (`.harness/ref/fe-<stack>.md`) 에서 로드한다.
 
-> **Flutter Web**: 컴파일 결과가 HTML+JS+CSS 이므로 React 경로의 Playwright evaluator 가 정상 동작.
-> Generator-Frontend-Flutter 의 Self-Verification 에서 `flutter analyze` / `flutter test` /
-> `flutter build web --release` 가 이미 통과한 상태로 handoff 됨이 전제.
+| 스택별 스킵/우회 | 방법 |
+|------------------|------|
+| Visual 렌더 검증이 불가능한 네이티브 모바일/데스크톱 | ref-docs 의 `validation.visual.enabled = false` — `evaluator-visual` 이 MANUAL_REQUIRED 로 우아하게 우회 |
+| Playwright 대신 스택 네이티브 E2E (예: XCUITest, Flutter `flutter_driver`) | ref-docs 의 `validation.functional_tests` 에 해당 명령 나열 — `evaluator-functional` 이 로드 실행 |
 
-Dispatcher는 `next_agent`를 설정할 때 `pipeline.json` 의 `fe_stack` + `fe_target` 두 값을 보고 치환한다:
-
-```
-if pipeline.json.fe_stack == "flutter":
-    "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__
-```
+Dispatcher 는 `fe_stack` 을 `pipeline.json` 에 기록만 하고, 에이전트 이름은 변경하지 않는다. Generator/Evaluator 는 세션 시작 시 스스로 ref-docs 를 로드해 스택에 맞는 동작을 한다.
 
 ## Evaluator Chain (공통)
 
@@ -83,10 +67,10 @@ agents:
   - planner (light):
       skip: MSA 서비스 설계, BE 기능 목록
       do: OpenAPI → api-contract.json 변환, FE 컴포넌트 설계, feature-list (layer: frontend만), fe_stack 확정
-  - generator-frontend OR generator-frontend-flutter  # fe_stack에 따라
+  - generator-frontend                                 # 모든 스택 공통 (ref-docs 로드)
   - evaluator-code-quality                             # 공통 — 브라우저 없음
-  - evaluator-functional OR evaluator-functional-flutter
-  - evaluator-visual  # fe_stack == "flutter" + fe_target in (mobile,desktop) 이면 SKIP
+  - evaluator-functional                               # 모든 스택 공통
+  - evaluator-visual                                   # ref.validation.visual.enabled=false 면 MANUAL_REQUIRED 로 우회
 evaluator_chain:
   - evaluator-code-quality
   - evaluator-functional
@@ -95,9 +79,9 @@ skip:
   - generator-backend
 notes:
   - api-contract.json은 OpenAPI에서 파생 (Planner가 변환)
-  - Eval-Func(React)의 API Health Check는 외부 서버 대상
+  - Eval-Func 의 API Health Check는 외부 서버 대상 (ref.api.base_url)
   - AGENTS.md IA-MAP에 BE 경로 없음 (외부 서버)
-  - fe_stack=flutter (mobile/desktop) 인 경우 evaluator-visual 생략
+  - 네이티브 모바일/데스크톱 스택은 ref-docs 에서 visual.enabled=false 로 설정
 ```
 
 ## BE-ONLY

package/skills/planner/SKILL.md

@@ -76,14 +76,15 @@ jq '.agent_status = "completed" | .completed_agents += ["planner"]'   .harness/p
 
 ## fe_stack (FE 파이프라인 분기)
 
-`pipeline.json.fe_stack`은 FE Generator/Evaluator 선택을 결정한다:
+`pipeline.json.fe_stack` 은 스택 기록용 메타데이터이며, **에이전트 이름 치환에는 사용되지 않는다** (v5.6.5+). 모든 스택이 공통 `generator-frontend` / `evaluator-functional` / `evaluator-visual` 을 사용하고, 스택별 동작(runner, paths, API, validation) 은 adaptive ref-docs(`.harness/ref/fe-<stack>.md`) 에서 로드한다.
 
-| 값 | FE Generator | FE Evaluator | 비고 |
-|----|--------------|--------------|------|
-| `react` (기본) | `generator-frontend` | `evaluator-functional` + `evaluator-visual` | Vercel/Next.js/Tailwind |
-| `flutter` | `generator-frontend-flutter` | `evaluator-functional-flutter` | Riverpod + integrated_data_layer, Eval-Visual 생략 |
+| 스택 예 | ref-docs 경로 | 비고 |
+|---------|--------------|------|
+| `react`, `nextjs` | `.harness/ref/fe-react.md`, `.harness/ref/fe-nextjs.md` | Vercel/Next.js/Tailwind |
+| `flutter` | `.harness/ref/fe-flutter.md` | Riverpod · validation.visual.enabled=false (모바일/데스크톱) |
+| `vue`, `svelte`, `swift` 등 | `.harness/ref/fe-<stack>.md` | 각 스택 관례 |
 
-**Planner는 `pipeline.json`에 `fe_stack`을 반드시 기록해야 한다.** Dispatcher가 이 값으로 `next_agent`를 라우팅한다.
+**Planner는 `pipeline.json`에 `fe_stack`을 반드시 기록해야 한다.** Generator/Evaluator 는 세션 시작 시 이 값으로 올바른 ref-docs 를 로드한다.
 
 ## Process
 

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

@@ -107,72 +107,58 @@ Flutter 프로젝트의 타깃을 확인합니다:
 이번 스프린트의 타깃은? (A/B/C)
 ```
 
-### fe_target → Eval 흐름
+### fe_target 과 Eval 흐름 (v5.6.5+)
 
-| fe_target | Generator | Eval-Functional | Eval-Visual |
-|-----------|-----------|----------------|-------------|
-| `web` | `generator-frontend-flutter` | `evaluator-functional` (Playwright!) | `evaluator-visual` (Playwright!) |
-| `mobile` | `generator-frontend-flutter` | `evaluator-functional-flutter` (정적 분석) | SKIP |
-| `desktop` | `generator-frontend-flutter` | `evaluator-functional-flutter` (정적 분석) | SKIP |
+에이전트 이름 치환은 하지 않는다. 모든 스택이 공통 `generator-frontend` / `evaluator-functional` / `evaluator-visual` 을 사용하고, 스택 특성은 `.harness/ref/fe-<stack>.md` (adaptive ref-docs) 의 `validation` 블록으로 조절된다.
 
-**핵심**: Flutter Web 의 빌드 결과물(HTML/JS/CSS)은 일반 웹앱과 동일하므로 Playwright 기반
-React 경로의 evaluator 를 그대로 재사용한다. Generator-Frontend-Flutter 의 Self-Verification
-단계에서 `flutter analyze`/`flutter test`/`flutter build web` 정적 검증이 이미 통과한 상태로 handoff 된다.
+| fe_target | 전략 | 방법 |
+|-----------|------|------|
+| `web` (Flutter Web, Next.js 등) | 일반 Playwright 평가 | ref.validation.visual.enabled = true |
+| `mobile` (iOS/Android 네이티브) | Visual 은 MANUAL_REQUIRED | ref.validation.visual.enabled = false + functional_tests 에 스택 네이티브 명령 |
+| `desktop` (macOS/Windows/Linux 네이티브) | Visual MANUAL_REQUIRED | 동일 |
+
+Generator 는 `ref.runner.dev_command` / `ref.paths.*` 를 로드해 스택별 빌드·테스트·구조를 따른다.
 
 ## 3. pipeline.json 갱신
 
-`fe_stack` + `fe_target` 확정 후 `pipeline.json`에 반드시 추가:
+`fe_stack` + `fe_target` 확정 후 `pipeline.json` 에 기록:
 
 ```json
 {
   "pipeline": "FULLSTACK",
   "planner_mode": "full",
   "fe_stack": "flutter",
-  "fe_target": "web",
+  "fe_target": "mobile",
   "agents_active": [
     "planner",
     "generator-backend",
-    "generator-frontend-flutter",
-    "evaluator-functional",
-    "evaluator-visual"
-  ],
-  "agents_skipped": [
     "generator-frontend",
-    "evaluator-functional-flutter"
+    "evaluator-code-quality",
+    "evaluator-functional"
   ],
-  "evaluator_mode": "playwright-web",
-  "notes": "Flutter Web — 컴파일 결과가 HTML+JS+CSS 이므로 React 경로의 Playwright evaluator 사용. Generator 의 Self-Verification 에서 flutter analyze/test 통과 전제."
+  "agents_skipped": [],
+  "evaluator_mode": "native",
+  "notes": "Flutter mobile — ref.validation.visual.enabled=false, evaluator-visual 은 MANUAL_REQUIRED 로 우회."
 }
 ```
 
 ### fe_stack + fe_target → 파이프라인 매핑
 
-| pipeline | fe_stack | fe_target | agents_active 예시 |
-|----------|----------|-----------|-------------------|
-| FULLSTACK | react | (n/a) | planner, generator-backend, generator-frontend, evaluator-functional, evaluator-visual |
-| FULLSTACK | flutter | **web** | planner, generator-backend, generator-frontend-flutter, evaluator-functional, evaluator-visual |
-| FULLSTACK | flutter | mobile | planner, generator-backend, generator-frontend-flutter, evaluator-functional-flutter |
-| FULLSTACK | flutter | desktop | planner, generator-backend, generator-frontend-flutter, evaluator-functional-flutter |
-| FE-ONLY | react | (n/a) | planner, generator-frontend, evaluator-functional, evaluator-visual |
-| FE-ONLY | flutter | **web** | planner, generator-frontend-flutter, evaluator-functional, evaluator-visual |
-| FE-ONLY | flutter | mobile | planner, generator-frontend-flutter, evaluator-functional-flutter |
-| BE-ONLY | (무관) | (n/a) | planner, generator-backend, evaluator-functional |
-
-## 4. Flutter 선택 시 추가 작업
-
-Flutter로 확정되면 Planner는:
-
-1. **AGENTS.md IA-MAP** 의 `[FE]` 섹션을 Flutter 구조로 바꿔야 한다.
-   - `apps/web/` → `lib/ui/pages/`, `lib/ui/component/`
-   - `libs/shared-dto/` 대신 `integrated_data_layer/` 경로 등록
-   - 소유자: `→ Generator-Frontend-Flutter`
+| pipeline | 에이전트 체인 (스택 무관) | ref-docs 로 조절되는 부분 |
+|----------|--------------------------|---------------------------|
+| FULLSTACK | planner → gen-be → gen-fe → eval-code-quality → eval-func → eval-visual | Gen/Eval 모두 ref.* 로드 |
+| FE-ONLY | planner(light) → gen-fe → eval-code-quality → eval-func → eval-visual | 동일 |
+| BE-ONLY | planner → gen-be → eval-code-quality → eval-func | visual 체인 없음 |
 
-2. **api-contract.json** 은 언어 중립적이어야 한다 — Planner는 TypeScript 타입이 아니라 **스키마 JSON** 으로만 작성. Flutter Generator가 Retrofit/JsonSerializable로 변환한다.
+## 4. Flutter 등 네이티브 스택 선택 시 추가 작업
 
-3. **feature-list.json** 의 `layer: "frontend"` feature들은 `fe_stack: "flutter"` 태그를 달아서 Evaluator가 구분하도록 한다.
+1. **AGENTS.md IA-MAP** 의 `[FE]` 섹션에 해당 스택 구조 반영 (예: Flutter 면 `lib/ui/pages/`, `integrated_data_layer/` 등).
+2. **api-contract.json** 은 언어 중립 스키마 JSON — Generator 가 스택 타입으로 변환.
+3. **feature-list.json** 의 `layer: "frontend"` feature 에 `fe_stack` 태그 유지 (필터링 용도).
+4. **`.harness/ref/fe-<stack>.md`** 의 `validation` 블록을 스택에 맞게 채워 두기 — 이게 실제 동작을 바꾸는 유일한 지점.
 
 ## 5. 금지
 
 - 파이프라인 실행 도중 `fe_stack` 변경 금지 — 스프린트 경계에서만 가능
-- React/Flutter 코드 혼재 생성 금지 — Generator는 하나의 stack만 담당
+- 서로 다른 스택 코드 혼재 생성 금지 — Generator 는 하나의 stack만 담당
 - 사용자가 명시적으로 한 스택을 지시했는데 감지 결과로 다른 스택을 강제하지 말 것