@walwal-harness/cli 5.6.2 → 5.6.4

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.2",
+  "version": "5.6.4",
   "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-progress-set.sh

@@ -0,0 +1,41 @@
+#!/bin/bash
+# harness-progress-set.sh — Safe partial update to .harness/progress.json
+#
+# Usage:
+#   bash scripts/harness-progress-set.sh <project-root> <jq_filter>
+#
+# The jq filter is a partial assignment expression. All other fields are
+# preserved. NEVER rewrite progress.json as a full JSON blob — mode,
+# team_state, and similar top-level fields will be lost.
+#
+# Example:
+#   bash scripts/harness-progress-set.sh . '.current_agent = "planner" | .agent_status = "running"'
+
+set -uo pipefail
+
+PROJECT_ROOT="${1:-.}"
+FILTER="${2:-}"
+
+if [ -z "$FILTER" ]; then
+  echo "[progress-set] usage: $0 <project-root> <jq_filter>" >&2
+  exit 2
+fi
+
+PROGRESS="$PROJECT_ROOT/.harness/progress.json"
+
+if [ ! -f "$PROGRESS" ]; then
+  echo "[progress-set] not found: $PROGRESS" >&2
+  exit 1
+fi
+
+# Always add .updated_at = now so callers don't forget
+FINAL_FILTER="$FILTER | .updated_at = (now | todate)"
+
+TMP="${PROGRESS}.tmp.$$"
+if jq "$FINAL_FILTER" "$PROGRESS" > "$TMP" 2>/dev/null; then
+  mv "$TMP" "$PROGRESS"
+else
+  rm -f "$TMP"
+  echo "[progress-set] jq filter failed: $FILTER" >&2
+  exit 1
+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/harness-session-start.sh

@@ -27,6 +27,29 @@ next_agent=$(jq -r '.next_agent // "none"' "$PROGRESS" 2>/dev/null)
 agent_status=$(jq -r '.agent_status // "pending"' "$PROGRESS" 2>/dev/null)
 mode=$(jq -r '.mode // "solo"' "$PROGRESS" 2>/dev/null)
 
+# ─────────────────────────────────────────
+# Auto-heal mode drift — Team 상태 유실 복구
+#   feature-queue.json 에 활성 작업(in_progress)이 있는데 mode 가 solo/paused 면
+#   누군가 progress.json 을 통째로 덮어써서 team_state 를 날린 것. mode=team 으로
+#   자동 복원하고 경고 로그 남김.
+# ─────────────────────────────────────────
+FEATURE_QUEUE_HEAL="$PROJECT_ROOT/.harness/actions/feature-queue.json"
+if [ -f "$FEATURE_QUEUE_HEAL" ] && [ "$mode" != "team" ]; then
+  active_count=$(jq -r '(.queue.in_progress | length) // 0' "$FEATURE_QUEUE_HEAL" 2>/dev/null || echo 0)
+  if [ "${active_count:-0}" -gt 0 ]; then
+    heal_teams=$active_count
+    [ "$heal_teams" -gt 3 ] && heal_teams=3
+    bash "$SCRIPT_DIR/harness-progress-set.sh" "$PROJECT_ROOT" \
+      ".mode = \"team\" | .team_state.active_teams = ${heal_teams} | .team_state.paused_at = null" \
+      2>/dev/null
+    mode="team"
+    echo "# Harness: mode auto-healed to 'team' (feature-queue has ${active_count} active, but mode was drifted)" >&2
+    if [ -f "$PROJECT_ROOT/.harness/progress.log" ]; then
+      echo "$(date +'%Y-%m-%d %H:%M') | system | heal | mode | reset solo→team (queue had ${active_count} in_progress)" >> "$PROJECT_ROOT/.harness/progress.log"
+    fi
+  fi
+fi
+
 # ─────────────────────────────────────────
 # Team Mode — 팀이 자율 실행 중이면 오케스트레이터 안내
 # ─────────────────────────────────────────

package/skills/brainstorming/SKILL.md

@@ -31,6 +31,24 @@ Planner 가 곧바로 plan.md / feature-list.json / api-contract.json 으로 변
 제공하거나 브레인스토밍 불필요를 선언하면 Dispatcher 는 곧바로 `next_agent = planner`
 로 라우팅한다.
 
+## progress.json 업데이트 규칙 (v5.6.3+)
+
+⚠️ **절대로 progress.json 을 통째로 재작성하지 마라**. `Write` 도구로 전체 파일을
+덮어쓰면 `mode` / `team_state` / 기타 top-level 필드가 누락되어 Team Mode 가 Solo 로
+되돌아가는 등 런타임 오류가 발생한다.
+
+**올바른 방법** — 반드시 partial update 로 갱신:
+
+```bash
+# 헬퍼 스크립트 (권장)
+bash scripts/harness-progress-set.sh . '.current_agent = "planner" | .agent_status = "running"'
+
+# 또는 직접 jq 로 partial update
+jq '.agent_status = "completed" | .completed_agents += ["planner"]'   .harness/progress.json > .harness/progress.json.tmp &&   mv .harness/progress.json.tmp .harness/progress.json
+```
+
+위 두 방식은 파일의 나머지 필드를 보존한다. Read → 수정 → Write 패턴은 사용 금지.
+
 ## Session Boundary Protocol
 
 ### On Start

package/skills/dispatcher/SKILL.md

@@ -6,6 +6,24 @@ disable-model-invocation: false
 
 # Dispatcher — Pipeline Selector + Gotcha Manager
 
+## progress.json 업데이트 규칙 (v5.6.3+)
+
+⚠️ **절대로 progress.json 을 통째로 재작성하지 마라**. `Write` 도구로 전체 파일을
+덮어쓰면 `mode` / `team_state` / 기타 top-level 필드가 누락되어 Team Mode 가 Solo 로
+되돌아가는 등 런타임 오류가 발생한다.
+
+**올바른 방법** — 반드시 partial update 로 갱신:
+
+```bash
+# 헬퍼 스크립트 (권장)
+bash scripts/harness-progress-set.sh . '.current_agent = "planner" | .agent_status = "running"'
+
+# 또는 직접 jq 로 partial update
+jq '.agent_status = "completed" | .completed_agents += ["planner"]'   .harness/progress.json > .harness/progress.json.tmp &&   mv .harness/progress.json.tmp .harness/progress.json
+```
+
+위 두 방식은 파일의 나머지 필드를 보존한다. Read → 수정 → Write 패턴은 사용 금지.
+
 ## Session Boundary Protocol
 
 ### On Start

package/skills/evaluator-code-quality/SKILL.md

@@ -9,6 +9,24 @@ disable-model-invocation: true
 > Functional/Visual 평가자보다 **먼저** 실행된다. 코드가 구조적으로 망가졌으면
 > 동작 테스트는 의미 없다. 이 게이트에서 FAIL 이면 Functional/Visual 은 아예 시작도 하지 않는다.
 
+## progress.json 업데이트 규칙 (v5.6.3+)
+
+⚠️ **절대로 progress.json 을 통째로 재작성하지 마라**. `Write` 도구로 전체 파일을
+덮어쓰면 `mode` / `team_state` / 기타 top-level 필드가 누락되어 Team Mode 가 Solo 로
+되돌아가는 등 런타임 오류가 발생한다.
+
+**올바른 방법** — 반드시 partial update 로 갱신:
+
+```bash
+# 헬퍼 스크립트 (권장)
+bash scripts/harness-progress-set.sh . '.current_agent = "planner" | .agent_status = "running"'
+
+# 또는 직접 jq 로 partial update
+jq '.agent_status = "completed" | .completed_agents += ["planner"]'   .harness/progress.json > .harness/progress.json.tmp &&   mv .harness/progress.json.tmp .harness/progress.json
+```
+
+위 두 방식은 파일의 나머지 필드를 보존한다. Read → 수정 → Write 패턴은 사용 금지.
+
 ## Session Boundary Protocol
 
 ### On Start

package/skills/evaluator-functional/SKILL.md

@@ -6,6 +6,24 @@ disable-model-invocation: true
 
 # Evaluator-Functional — Playwright MCP
 
+## progress.json 업데이트 규칙 (v5.6.3+)
+
+⚠️ **절대로 progress.json 을 통째로 재작성하지 마라**. `Write` 도구로 전체 파일을
+덮어쓰면 `mode` / `team_state` / 기타 top-level 필드가 누락되어 Team Mode 가 Solo 로
+되돌아가는 등 런타임 오류가 발생한다.
+
+**올바른 방법** — 반드시 partial update 로 갱신:
+
+```bash
+# 헬퍼 스크립트 (권장)
+bash scripts/harness-progress-set.sh . '.current_agent = "planner" | .agent_status = "running"'
+
+# 또는 직접 jq 로 partial update
+jq '.agent_status = "completed" | .completed_agents += ["planner"]'   .harness/progress.json > .harness/progress.json.tmp &&   mv .harness/progress.json.tmp .harness/progress.json
+```
+
+위 두 방식은 파일의 나머지 필드를 보존한다. Read → 수정 → Write 패턴은 사용 금지.
+
 ## Session Boundary Protocol
 
 ### On Start

package/skills/evaluator-visual/SKILL.md

@@ -6,6 +6,24 @@ disable-model-invocation: true
 
 # Evaluator-Visual — Design & Accessibility
 
+## progress.json 업데이트 규칙 (v5.6.3+)
+
+⚠️ **절대로 progress.json 을 통째로 재작성하지 마라**. `Write` 도구로 전체 파일을
+덮어쓰면 `mode` / `team_state` / 기타 top-level 필드가 누락되어 Team Mode 가 Solo 로
+되돌아가는 등 런타임 오류가 발생한다.
+
+**올바른 방법** — 반드시 partial update 로 갱신:
+
+```bash
+# 헬퍼 스크립트 (권장)
+bash scripts/harness-progress-set.sh . '.current_agent = "planner" | .agent_status = "running"'
+
+# 또는 직접 jq 로 partial update
+jq '.agent_status = "completed" | .completed_agents += ["planner"]'   .harness/progress.json > .harness/progress.json.tmp &&   mv .harness/progress.json.tmp .harness/progress.json
+```
+
+위 두 방식은 파일의 나머지 필드를 보존한다. Read → 수정 → Write 패턴은 사용 금지.
+
 ## Session Boundary Protocol
 
 ### On Start

package/skills/generator-backend/SKILL.md

@@ -6,6 +6,24 @@ disable-model-invocation: true
 
 # Generator-Backend — Adaptive (Stack-Agnostic)
 
+## progress.json 업데이트 규칙 (v5.6.3+)
+
+⚠️ **절대로 progress.json 을 통째로 재작성하지 마라**. `Write` 도구로 전체 파일을
+덮어쓰면 `mode` / `team_state` / 기타 top-level 필드가 누락되어 Team Mode 가 Solo 로
+되돌아가는 등 런타임 오류가 발생한다.
+
+**올바른 방법** — 반드시 partial update 로 갱신:
+
+```bash
+# 헬퍼 스크립트 (권장)
+bash scripts/harness-progress-set.sh . '.current_agent = "planner" | .agent_status = "running"'
+
+# 또는 직접 jq 로 partial update
+jq '.agent_status = "completed" | .completed_agents += ["planner"]'   .harness/progress.json > .harness/progress.json.tmp &&   mv .harness/progress.json.tmp .harness/progress.json
+```
+
+위 두 방식은 파일의 나머지 필드를 보존한다. Read → 수정 → Write 패턴은 사용 금지.
+
 ## Session Boundary Protocol
 
 ### On Start

package/skills/generator-frontend/SKILL.md

@@ -6,6 +6,24 @@ disable-model-invocation: true
 
 # Generator-Frontend — Adaptive (Stack-Agnostic)
 
+## progress.json 업데이트 규칙 (v5.6.3+)
+
+⚠️ **절대로 progress.json 을 통째로 재작성하지 마라**. `Write` 도구로 전체 파일을
+덮어쓰면 `mode` / `team_state` / 기타 top-level 필드가 누락되어 Team Mode 가 Solo 로
+되돌아가는 등 런타임 오류가 발생한다.
+
+**올바른 방법** — 반드시 partial update 로 갱신:
+
+```bash
+# 헬퍼 스크립트 (권장)
+bash scripts/harness-progress-set.sh . '.current_agent = "planner" | .agent_status = "running"'
+
+# 또는 직접 jq 로 partial update
+jq '.agent_status = "completed" | .completed_agents += ["planner"]'   .harness/progress.json > .harness/progress.json.tmp &&   mv .harness/progress.json.tmp .harness/progress.json
+```
+
+위 두 방식은 파일의 나머지 필드를 보존한다. Read → 수정 → Write 패턴은 사용 금지.
+
 ## Session Boundary Protocol
 
 ### On Start

package/skills/planner/SKILL.md

@@ -6,6 +6,24 @@ disable-model-invocation: true
 
 # Planner Agent
 
+## progress.json 업데이트 규칙 (v5.6.3+)
+
+⚠️ **절대로 progress.json 을 통째로 재작성하지 마라**. `Write` 도구로 전체 파일을
+덮어쓰면 `mode` / `team_state` / 기타 top-level 필드가 누락되어 Team Mode 가 Solo 로
+되돌아가는 등 런타임 오류가 발생한다.
+
+**올바른 방법** — 반드시 partial update 로 갱신:
+
+```bash
+# 헬퍼 스크립트 (권장)
+bash scripts/harness-progress-set.sh . '.current_agent = "planner" | .agent_status = "running"'
+
+# 또는 직접 jq 로 partial update
+jq '.agent_status = "completed" | .completed_agents += ["planner"]'   .harness/progress.json > .harness/progress.json.tmp &&   mv .harness/progress.json.tmp .harness/progress.json
+```
+
+위 두 방식은 파일의 나머지 필드를 보존한다. Read → 수정 → Write 패턴은 사용 금지.
+
 ## Session Boundary Protocol
 
 ### On Start