@walwal-harness/cli 5.6.4 → 5.7.0

package/assets/templates/progress.json.template

@@ -1,8 +1,12 @@
 {
-  "version": 2,
+  "version": 3,
   "mode": "solo",
   "project_name": "",
   "pipeline": null,
+  "dispatch": {
+    "counter": 0,
+    "id": null
+  },
   "sprint": {
     "number": 0,
     "status": "init",

package/bin/init.js

@@ -346,6 +346,14 @@ function scaffoldHarness() {
         fs.writeFileSync(progressPath, JSON.stringify(progress, null, 2) + '\n');
         log('progress.json migrated to v2 (mode + team_state added)');
       }
+      if (progress.version < 3) {
+        progress.version = 3;
+        if (!progress.dispatch) {
+          progress.dispatch = { counter: 0, id: null };
+        }
+        fs.writeFileSync(progressPath, JSON.stringify(progress, null, 2) + '\n');
+        log('progress.json migrated to v3 (dispatch counter added)');
+      }
     } catch (e) {
       log('WARNING: Could not migrate progress.json');
     }

package/commands/harness-team.md

@@ -59,6 +59,39 @@ bash scripts/harness-tmux.sh --team --force-tmux
 
 **`--force-tmux` 필수**: iTerm2 감지 경로는 백그라운드에 iTerm2가 떠 있기만 해도 활성화되어 AppleScript 실패 시 팀 레이아웃이 조용히 사라짐. Team Mode는 항상 tmux로 강제하여 재현 가능한 레이아웃을 보장.
 
+### Step 2.5: Worker Pre-flight Bundle 빌드 (v5.6.6+)
+
+Worker 는 plain Agent 로 실행되어 SKILL.md Startup 체크리스트를 자동 주입받지 못한다. Lead 가 Worker spawn 직전에 **역할별 바인딩 문서를 프롬프트에 직접 주입**한다. 이렇게 하면 "Worker 가 읽어야 함" → "이미 읽은 상태로 시작" 으로 전환되어 스킵이 구조적으로 불가능해진다.
+
+```bash
+# Generator-{be|fe} / Evaluator-{functional|visual|code-quality} 별 번들 빌드
+build_preflight_bundle() {
+  local role="$1"   # generator-frontend | generator-backend | evaluator-functional | ...
+  local hroot="$2"  # HARNESS_ROOT (worktree 가 아닌 원본 루트)
+  {
+    echo "===== ROOT CONVENTIONS.md ====="
+    [ -f "$hroot/CONVENTIONS.md" ] && cat "$hroot/CONVENTIONS.md" || echo "(none)"
+    echo
+    echo "===== AGENTS.md ====="
+    [ -f "$hroot/AGENTS.md" ] && cat "$hroot/AGENTS.md" || echo "(none)"
+    echo
+    echo "===== .harness/conventions/shared.md ====="
+    [ -f "$hroot/.harness/conventions/shared.md" ] && cat "$hroot/.harness/conventions/shared.md" || echo "(empty)"
+    echo
+    echo "===== .harness/conventions/$role.md ====="
+    [ -f "$hroot/.harness/conventions/$role.md" ] && cat "$hroot/.harness/conventions/$role.md" || echo "(empty)"
+    echo
+    echo "===== .harness/gotchas/$role.md ====="
+    [ -f "$hroot/.harness/gotchas/$role.md" ] && cat "$hroot/.harness/gotchas/$role.md" || echo "(empty)"
+    echo
+    echo "===== .harness/memory.md ====="
+    [ -f "$hroot/.harness/memory.md" ] && cat "$hroot/.harness/memory.md" || echo "(empty)"
+  }
+}
+```
+
+Worker/내부 Evaluator Agent 프롬프트 상단에 이 번들 출력을 `## Binding Rules (pre-loaded)` 섹션으로 삽입한다. Worker 는 이를 **추가 조회 없이 이미 적용되는 규범**으로 취급한다.
+
 ### Step 3: 초기 Worker 생성 (Auto-Dispatch)
 
 **v5.6.4+**: 개별 dequeue 대신 **`auto-dispatch`** 한 번으로 모든 idle team 에 ready feature 를 원자적으로 배정합니다. 의존성 없는 작업은 병렬로 즉시 시작됩니다.
@@ -97,10 +130,11 @@ ORCHESTRATION LOOP:
 
   Background Agent 완료 알림을 받으면:
 
-  1. Worker 결과 분석:
-     - PASS인 경우 → Step 4a (Merge + Unblock)
-     - FAIL (재시도 가능)인 경우 → Step 4b (Retry)
-     - ESCALATED인 경우 → 사용자에게 알림, 해당 팀 유휴
+  1. Worker 결과 분석 (반환 메시지 첫 줄 태그로 분기):
+     - `PASS` → Step 4a (Merge + Unblock)
+     - `FAIL` (재시도 가능) → Step 4b (Retry)
+     - `RATE_LIMIT` → Step 4c (Rate-Limit Hold, 10m probe)
+     - `ESCALATED` → 사용자에게 알림, 해당 팀 유휴
 
   2. **Auto-Dispatch (필수)** — worker 완료 직후 idle 이 된 팀뿐 아니라
      모든 idle team 에 ready feature 를 즉시 재배정:
@@ -145,6 +179,47 @@ Worker가 PASS로 반환되면:
    echo "$(date +'%Y-%m-%d %H:%M') | lead | pass | {FEATURE_ID} merged + unblocked deps" >> .harness/progress.log
    ```
 
+#### Step 4c: Rate-Limit Hold (토큰 한도 대응 · v5.6.7+)
+
+Worker 반환 첫 줄이 `RATE_LIMIT` 으로 시작하면 Lead 는 **에러 아닌 hold 모드**로 전환한다. 나머지 Worker 들은 자연 완료까지 계속 실행되고, 그 결과도 RATE_LIMIT 이면 합쳐서 hold 상태에 누적된다.
+
+```bash
+# 1) Checkpoint 기록 (current in_progress + ready 스냅샷 저장)
+bash "$HARNESS_ROOT/scripts/harness-queue-manager.sh" hold rate_limit 600 .
+
+# 2) 로그 + tmux pane 타이틀 변경
+echo "$(date +'%Y-%m-%d %H:%M') | lead | hold | rate-limit detected, pausing 10m" >> .harness/progress.log
+tmux rename-window "⏸ HOLD (resume ~$(date -v+10M +%H:%M 2>/dev/null || date -d '+10 min' +%H:%M))" 2>/dev/null || true
+
+# 3) 실패한 feature 는 requeue (WIP worktree 는 유지 — merge 없이 재사용)
+bash "$HARNESS_ROOT/scripts/harness-queue-manager.sh" requeue {FEATURE_ID} .
+```
+
+4) **ScheduleWakeup 으로 10분 뒤 재진입 스케줄**:
+```
+ScheduleWakeup({
+  delaySeconds: 600,
+  prompt: "/harness-team resume",
+  reason: "rate-limit hold — 10m probe"
+})
+```
+
+5) Lead LOOP return (중단 아님 — wake-up 이 재진입 트리거).
+
+**Wake-up 재진입 시 Lead 동작** (`/harness-team resume` 처리):
+
+```bash
+# Probe: claude CLI 가 실제로 응답하는지 최소 호출로 확인
+bash "$HARNESS_ROOT/scripts/harness-queue-manager.sh" resume-probe .
+# 종료 코드: 0=clear, 1=still held, 2=escalated(>12h)
+```
+
+- **0 (clear)** → 체크포인트 삭제됨. 즉시 `auto-dispatch` 실행 → Step 4 LOOP 복귀.
+- **1 (still held)** → 다시 `ScheduleWakeup(600, "/harness-team resume", "rate-limit still held — cycle N")` 스케줄. hold_count 증가.
+- **2 (escalated)** → 72 사이클(12시간) 초과. 사용자 개입 알림 후 LOOP 종료. 체크포인트 파일 (`.harness/actions/team-checkpoint.json`) 에 전체 상태가 남아있으므로 사용자가 수동 복구 가능.
+
+**핵심 원칙**: 토큰 리밋은 "실패"가 아닌 "일시 정지". 진행 중이던 worktree/queue 상태는 그대로 보존되고, 10분 간격 probe 로 해제 즉시 이어서 진행한다. Session 을 닫아도 이어지길 원한다면 `ScheduleWakeup` 대신 `schedule` 스킬(CronCreate) 로 cron-backed 재시도 설정 가능.
+
 #### Step 4b: Retry (FAIL 처리)
 
 Worker가 FAIL (재시도 가능)로 반환되면:
@@ -171,6 +246,15 @@ Worker가 FAIL (재시도 가능)로 반환되면:
 당신은 Harness Team-{N} 워커입니다. **단일 Feature**에 대해 Gen→Eval 사이클을 수행합니다.
 완료 후 결과를 반환합니다. 다음 Feature는 Lead가 할당합니다.
 
+## Binding Rules (pre-loaded — 스킵 금지, 이미 적용됨)
+
+Lead 가 Step 2.5 에서 build_preflight_bundle 로 생성한 번들이 아래에 주입됩니다.
+당신은 이 규칙을 이미 읽은 상태로 시작합니다. 추가 조회 불필요:
+
+{PREFLIGHT_BUNDLE}
+
+**작업 시작 전 필수 출력**: 위 번들에서 이번 Feature 작업에 **적용되는 규칙**을 3~8 줄로 요약한 뒤 진행하라. 비어있으면 "(empty)" 로 명시. 이 요약 없이 Phase 1 로 진입하면 Self-FAIL 처리하고 재시작한다. 내부 Evaluator Agent 를 생성할 때도 같은 번들을 `{PREFLIGHT_BUNDLE}` 자리에 그대로 전달하라 (Evaluator 도 plain Agent 이므로 자동주입 없음).
+
 ## 할당된 Feature
 - Feature ID: {FEATURE_ID}
 - 프로젝트 루트: 현재 디렉토리 (worktree 복사본)
@@ -301,6 +385,18 @@ logev fail "{FEATURE_ID} FAIL #{ATTEMPT} — {사유}"
 logev fail "{FEATURE_ID} FINAL FAIL after 5 attempts"
 ```
 Lead에게 반환: `ESCALATED | {FEATURE_ID} | attempts=5 | last_feedback={마지막_피드백}`
+
+### RATE_LIMIT (토큰 한도 감지 시 — v5.6.7+)
+
+Gen 또는 Eval Phase 중 429 / "rate_limit" / "quota" / "overloaded_error" / "token limit" / "usage limit" 메시지를 만나면:
+
+```bash
+logev hold "{FEATURE_ID} rate-limit hit — returning RATE_LIMIT to Lead"
+```
+Lead에게 반환 **첫 줄에 반드시 `RATE_LIMIT` 태그 포함**:
+`RATE_LIMIT | {FEATURE_ID} | phase={gen|eval} | attempt={N} | err={원문요약}`
+
+작업을 **포기하지 말고** 현재까지의 변경분을 worktree 에 그대로 commit (WIP). Lead 가 hold 해제 후 같은 worktree 로 resume.
 ```
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@walwal-harness/cli",
-  "version": "5.6.4",
+  "version": "5.7.0",
   "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-archive.sh

@@ -0,0 +1,109 @@
+#!/bin/bash
+# harness-archive.sh — 스프린트 종료 시 자동 아카이빙
+#
+# 동작:
+#   1. .harness/actions/ 의 스프린트 산출물을 .harness/archive/D-NNN/S-NNN/ 로 이동
+#   2. progress.json 의 sprint 상태를 초기화 (신규 dispatch 준비)
+#   3. dispatch.id 가 없으면 counter++ 로 새 dispatch 시작
+#
+# 유지되는 파일 (이동하지 않음):
+#   - .harness/gotchas/**, .harness/conventions/**, .harness/ref/**
+#   - .harness/config.json, .harness/memory.md
+#   - .harness/progress.json (초기화만)
+#
+# 호출 주체: harness-next.sh (next_agent="archive" 도달 시 자동)
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+source "$SCRIPT_DIR/lib/harness-render-progress.sh" 2>/dev/null || true
+
+PROJECT_ROOT="${1:-.}"
+PROJECT_ROOT="$(cd "$PROJECT_ROOT" && pwd)"
+
+PROGRESS="$PROJECT_ROOT/.harness/progress.json"
+ACTIONS_DIR="$PROJECT_ROOT/.harness/actions"
+ARCHIVE_ROOT="$PROJECT_ROOT/.harness/archive"
+
+if [ ! -f "$PROGRESS" ]; then
+  echo "[archive] ERROR: progress.json not found" >&2
+  exit 1
+fi
+
+command -v jq >/dev/null 2>&1 || { echo "[archive] ERROR: jq required" >&2; exit 1; }
+
+# ── Read current dispatch/sprint numbers ──
+dispatch_counter=$(jq -r '.dispatch.counter // 0' "$PROGRESS")
+dispatch_id=$(jq -r '.dispatch.id // empty' "$PROGRESS")
+sprint_num=$(jq -r '.sprint.number // 0' "$PROGRESS")
+
+# Ensure dispatch id exists (fallback for legacy progress.json without dispatch)
+if [ -z "$dispatch_id" ] || [ "$dispatch_id" = "null" ]; then
+  if [ "$dispatch_counter" -lt 1 ]; then
+    dispatch_counter=1
+  fi
+  dispatch_id=$(printf 'D-%03d' "$dispatch_counter")
+fi
+
+sprint_id=$(printf 'S-%03d' "$sprint_num")
+target_dir="$ARCHIVE_ROOT/$dispatch_id/$sprint_id"
+
+echo ""
+echo "  ── Archive ────────────────────────────"
+echo "  Dispatch : $dispatch_id"
+echo "  Sprint   : $sprint_id"
+echo "  Target   : ${target_dir#$PROJECT_ROOT/}"
+
+# ── Move actions/ contents into archive ──
+if [ -d "$ACTIONS_DIR" ] && [ "$(ls -A "$ACTIONS_DIR" 2>/dev/null)" ]; then
+  mkdir -p "$target_dir"
+  moved=0
+  for f in "$ACTIONS_DIR"/*; do
+    [ -e "$f" ] || continue
+    name="$(basename "$f")"
+    if [ -e "$target_dir/$name" ]; then
+      # Collision — suffix with timestamp to avoid overwrite
+      ts=$(date +%Y%m%d-%H%M%S)
+      mv "$f" "$target_dir/${name%.}.${ts}"
+    else
+      mv "$f" "$target_dir/"
+    fi
+    moved=$((moved + 1))
+  done
+  echo "  Moved    : $moved file(s)"
+else
+  echo "  Moved    : 0 file(s) (actions/ empty)"
+fi
+
+# ── Reset progress.json for next dispatch ──
+# - sprint → init
+# - agents → cleared
+# - artifacts → pending
+# - dispatch.id cleared (next dispatcher run will allocate new D-NNN)
+# - failure → cleared
+jq --arg now "$(date -u +%Y-%m-%dT%H:%M:%SZ)" '
+  .pipeline = null
+  | .dispatch.id = null
+  | .sprint = { number: 0, status: "init", retry_count: 0 }
+  | .current_agent = null
+  | .agent_status = "pending"
+  | .completed_agents = []
+  | .next_agent = "dispatcher"
+  | .failure = { agent: null, location: null, message: null, retry_target: null }
+  | (.artifacts // {}) as $a
+  | .artifacts = ($a | with_entries(
+      if (.value | type) == "object"
+      then .value = { status: "pending", updated_by: null, updated_at: null }
+      else .
+      end))
+  | .updated_at = $now
+' "$PROGRESS" > "${PROGRESS}.tmp" && mv "${PROGRESS}.tmp" "$PROGRESS"
+
+# ── Clear handoff so next session starts fresh ──
+HANDOFF="$PROJECT_ROOT/.harness/handoff.json"
+echo '{}' > "$HANDOFF"
+
+echo "  Status   : archived, progress reset"
+echo ""
+echo "  ✓ 다음 요청은 새로운 dispatch 로 시작합니다."
+echo ""

package/scripts/harness-dashboard.sh

@@ -11,6 +11,7 @@ set -uo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 source "$SCRIPT_DIR/lib/harness-render-progress.sh"
+source "$SCRIPT_DIR/lib/harness-keywait.sh"
 
 PROJECT_ROOT="${1:-}"
 if [ -z "$PROJECT_ROOT" ]; then
@@ -420,5 +421,6 @@ while true; do
   # from any previous frame (fixes wrapped shell-prompt bleed-through).
   printf '%s\n' "$buf" | awk '{printf "%s\033[K\n", $0}'
   tput ed 2>/dev/null
-  sleep 3
+  printf "${DIM}  [r] refresh  [q] quit${RESET}\033[K\n"
+  wait_or_refresh 3 || true
 done

package/scripts/harness-gotcha-memory.sh

@@ -7,6 +7,7 @@ set -uo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 source "$SCRIPT_DIR/lib/harness-render-progress.sh"
+source "$SCRIPT_DIR/lib/harness-keywait.sh"
 
 PROJECT_ROOT="${1:-}"
 if [ -z "$PROJECT_ROOT" ]; then
@@ -181,7 +182,11 @@ while true; do
   sig=$(compute_signature)
   if [ "$sig" != "$LAST_SIG" ]; then
     render
+    printf "${DIM}  [r] refresh  [q] quit${RESET}\033[K\n"
     LAST_SIG="$sig"
   fi
-  sleep "$REFRESH_SEC"
+  if ! wait_or_refresh "$REFRESH_SEC"; then
+    # 'r' 키 → 캐시 무효화해서 다음 루프에서 강제 렌더
+    LAST_SIG=""
+  fi
 done

package/scripts/harness-monitor.sh

@@ -9,6 +9,7 @@
 set -uo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+source "$SCRIPT_DIR/lib/harness-keywait.sh"
 
 # ── Args ──
 # Usage: harness-monitor.sh [project-root] [--team N]
@@ -382,6 +383,7 @@ while true; do
     check_transitions
   fi
 
-  sleep 3
+  printf "${DIM}  [r] refresh  [q] quit${RESET}\033[K\n"
+  wait_or_refresh 3 || true
 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
 
@@ -499,19 +499,29 @@ if [ "$next_agent" != "null" ] && [ "$next_agent" != "archive" ] && [ "$agent_st
 
 elif [ "$next_agent" = "archive" ]; then
   audit_log "system" "archive" "start" "sprint-${sprint_num}" "sprint cycle complete"
-  jq -n \
-    --arg from "${current_agent:-evaluator}" \
-    --argjson sprint "$sprint_num" \
-    --arg timestamp "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
-    '{
-      from: $from,
-      to: "archive",
-      prompt: "Sprint 문서를 아카이브하세요.\n.harness/actions/의 스프린트 문서를 .harness/archive/sprint-NNN/으로 이동합니다.\n.harness/handoff.json을 읽고 sprint 번호를 확인하세요.",
-      sprint: $sprint,
-      model: "opus",
-      thinking_mode: null,
-      timestamp: $timestamp
-    }' > "$HANDOFF"
+
+  # ── Auto-archive: run archive script synchronously ──
+  # harness-archive.sh moves .harness/actions/* to .harness/archive/D-NNN/S-NNN/
+  # and resets progress.json. On next user prompt the flow starts fresh as a new dispatch.
+  if bash "$SCRIPT_DIR/harness-archive.sh" "$PROJECT_ROOT"; then
+    audit_log "system" "archive" "complete" "sprint-${sprint_num}" "auto-archived"
+  else
+    echo "  ⚠ archive script failed — falling back to manual handoff" >&2
+    audit_log "system" "archive" "fail" "sprint-${sprint_num}" "script failed"
+    jq -n \
+      --arg from "${current_agent:-evaluator}" \
+      --argjson sprint "$sprint_num" \
+      --arg timestamp "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+      '{
+        from: $from,
+        to: "archive",
+        prompt: "Sprint 문서를 아카이브하세요. harness-archive.sh 가 실패했습니다 — 수동으로 .harness/actions/* 를 .harness/archive/D-NNN/S-NNN/ 로 이동하세요.",
+        sprint: $sprint,
+        model: "opus",
+        thinking_mode: null,
+        timestamp: $timestamp
+      }' > "$HANDOFF"
+  fi
 
 else
   echo '{}' > "$HANDOFF"

package/scripts/harness-prompt-history.sh

@@ -7,6 +7,7 @@ set -uo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 source "$SCRIPT_DIR/lib/harness-render-progress.sh"
+source "$SCRIPT_DIR/lib/harness-keywait.sh"
 
 PROJECT_ROOT="${1:-}"
 if [ -z "$PROJECT_ROOT" ]; then
@@ -158,5 +159,6 @@ while true; do
   tput cup 0 0 2>/dev/null
   echo "$buf"
   tput ed 2>/dev/null
-  sleep 3
+  printf "${DIM}  [r] refresh  [q] quit${RESET}\033[K\n"
+  wait_or_refresh 3 || true
 done

package/scripts/harness-queue-manager.sh

@@ -487,6 +487,68 @@ cmd_idle_slots() {
   }' "$QUEUE"
 }
 
+# ── Rate-Limit Hold checkpoint (v5.6.7+) ──
+CHECKPOINT="$PROJECT_ROOT/.harness/actions/team-checkpoint.json"
+
+cmd_hold() {
+  # Args: <reason> [retry_seconds=600]
+  local reason="${1:-rate_limit}"
+  local retry_secs="${2:-600}"
+  local now_iso retry_iso
+  now_iso="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+  retry_iso="$(date -u -v+"${retry_secs}"S +%Y-%m-%dT%H:%M:%SZ 2>/dev/null \
+              || date -u -d "+${retry_secs} seconds" +%Y-%m-%dT%H:%M:%SZ)"
+  acquire_queue_lock
+  trap release_queue_lock EXIT
+  local in_progress pending
+  in_progress="$(jq '[.teams[] | select(.current_feature != null) |
+                     {team: .team_id, feature: .current_feature, phase: (.current_phase // "gen")}]' "$QUEUE")"
+  pending="$(jq '[.features[] | select(.status == "ready") | .id]' "$QUEUE")"
+  local tmp="${CHECKPOINT}.tmp"
+  jq -n --arg ts "$now_iso" --arg retry "$retry_iso" --arg reason "$reason" \
+        --argjson inprog "$in_progress" --argjson ready "$pending" \
+        '{timestamp:$ts, retry_at:$retry, last_error:$reason,
+          in_progress:$inprog, ready_features:$ready,
+          hold_count: 1, escalate_after: 72}' > "$tmp" && mv "$tmp" "$CHECKPOINT"
+  release_queue_lock
+  trap - EXIT
+  echo "[hold] checkpoint written — retry_at=$retry_iso reason=$reason"
+}
+
+cmd_resume_probe() {
+  # Lightweight probe — called on ScheduleWakeup resume.
+  # Exits 0 if ready to resume, 1 if still held, 2 if escalated.
+  [ ! -f "$CHECKPOINT" ] && { echo "[resume] no checkpoint — nothing to resume"; exit 0; }
+  local hold_count escalate_after
+  hold_count="$(jq -r '.hold_count // 1' "$CHECKPOINT")"
+  escalate_after="$(jq -r '.escalate_after // 72' "$CHECKPOINT")"
+  if [ "$hold_count" -ge "$escalate_after" ]; then
+    echo "[resume] ESCALATED — held $hold_count cycles (max=$escalate_after). Manual intervention required."
+    exit 2
+  fi
+  # Probe: minimal claude call — if rate-limited, exits non-zero quickly.
+  if command -v claude >/dev/null 2>&1; then
+    if echo "ping" | timeout 30 claude -p "reply only: pong" >/dev/null 2>&1; then
+      echo "[resume] probe OK — clearing hold"
+      rm -f "$CHECKPOINT"
+      exit 0
+    fi
+  fi
+  # Still held — increment and report
+  local tmp="${CHECKPOINT}.tmp"
+  jq '.hold_count = (.hold_count + 1) | .last_probe_at = now | todate' "$CHECKPOINT" > "$tmp" && mv "$tmp" "$CHECKPOINT"
+  echo "[resume] still held (cycle $((hold_count+1))/$escalate_after) — schedule another wake-up"
+  exit 1
+}
+
+cmd_hold_status() {
+  if [ ! -f "$CHECKPOINT" ]; then
+    echo '{"held":false}'
+    return
+  fi
+  jq '. + {held:true}' "$CHECKPOINT"
+}
+
 # ── Dispatch ──
 case "$CMD" in
   init)           cmd_init "$@" ;;
@@ -500,8 +562,11 @@ case "$CMD" in
   recover)        cmd_recover ;;
   next-sprint)    cmd_next_sprint ;;
   status)         cmd_status ;;
+  hold)           cmd_hold "$@" ;;
+  resume-probe)   cmd_resume_probe ;;
+  hold-status)    cmd_hold_status ;;
   *)
-    echo "Usage: harness-queue-manager.sh <init|dequeue|auto-dispatch|idle-slots|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|hold|resume-probe|hold-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-keywait.sh

@@ -0,0 +1,57 @@
+#!/bin/bash
+# harness-keywait.sh — 패널 refresh/quit 키 대기 헬퍼
+#
+# 사용법:
+#   source scripts/lib/harness-keywait.sh
+#   while true; do
+#     render_panel
+#     echo "  [r] refresh  [q] quit"
+#     if wait_or_refresh 3; then
+#       # 타임아웃 → 일반 주기 리프레시
+#       :
+#     else
+#       # 'r' 키 즉시 리프레시 (반환값 != 0)
+#       :
+#     fi
+#   done
+#
+# 키 처리:
+#   'r' / 'R' / Enter → 즉시 복귀 (return 1 — 강제 리프레시 신호)
+#   'q' / 'Q'         → exit 0 (패널 종료)
+#   그 외 / 타임아웃  → return 0 (정상 주기 리프레시)
+#
+# TTY 가 아니면 plain sleep 으로 동작 (Claude Code Bash 도구 등에서도 안전).
+
+wait_or_refresh() {
+  local secs="${1:-3}"
+
+  # Non-TTY fallback
+  if ! [ -t 0 ]; then
+    sleep "$secs"
+    return 0
+  fi
+
+  local key=""
+  # -t: timeout, -n 1: 1글자, -s: 에코 안함
+  # read 는 Enter 에서도 타임아웃 전에 즉시 복귀 (빈 키)
+  if IFS= read -rsn 1 -t "$secs" key 2>/dev/null; then
+    case "$key" in
+      q|Q)
+        # 커서 복원 후 종료
+        tput cnorm 2>/dev/null || true
+        clear
+        exit 0
+        ;;
+      r|R|"")
+        # 강제 리프레시 시그널
+        return 1
+        ;;
+      *)
+        # 기타 키는 무시하고 일반 복귀
+        return 0
+        ;;
+    esac
+  fi
+  # 타임아웃
+  return 0
+}

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

@@ -42,6 +42,18 @@ jq '.agent_status = "completed" | .completed_agents += ["planner"]'   .harness/p
      - Gotcha 교정 후 재작업 → `failure.retry_target` (해당 에이전트)
    - `pipeline` → 선택된 파이프라인 (FULLSTACK/FE-ONLY/BE-ONLY)
    - `sprint.number` → `1`, `sprint.status` → `"in_progress"` (신규 파이프라인인 경우에만)
+   - **신규 파이프라인인 경우** `dispatch.id` 가 `null` 이면 counter 를 올리고 새 ID 를 발급 (v5.7+):
+     ```bash
+     # dispatch.id 가 이미 있으면 기존 dispatch 유지, 없으면 새로 발급
+     cur=$(jq -r '.dispatch.id // ""' .harness/progress.json)
+     if [ -z "$cur" ]; then
+       next=$(jq -r '((.dispatch.counter // 0) + 1)' .harness/progress.json)
+       new_id=$(printf 'D-%03d' "$next")
+       bash scripts/harness-progress-set.sh . \
+         ".dispatch.counter = $next | .dispatch.id = \"$new_id\""
+     fi
+     ```
+     아카이빙 후 `dispatch.id` 는 `null` 로 리셋되므로, 다음 dispatcher 실행 시 새 D-NNN 이 할당된다.
 2. `.harness/progress.log`에 요약 한 줄 추가
 3. **STOP. 다음 에이전트를 직접 호출하지 않는다.**
 4. 출력: `"✓ Dispatcher 완료. bash scripts/harness-next.sh 실행하여 다음 단계 확인."`
@@ -147,7 +159,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 +175,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 +232,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 +250,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만 담당
 - 사용자가 명시적으로 한 스택을 지시했는데 감지 결과로 다른 스택을 강제하지 말 것