@walwal-harness/cli 5.2.0 → 5.3.1

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.2.0",
+  "version": "5.3.1",
   "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,187 @@
+#!/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}"
+
+# 렌더 캐시 — 내용이 바뀌지 않으면 redraw 스킵
+LAST_SIG=""
+
+# 입력 시그니처: gotchas + memory + 활성 에이전트의 mtime/size 해시
+compute_signature() {
+  {
+    [ -f "$PROGRESS" ] && stat -f '%m %z' "$PROGRESS" 2>/dev/null
+    [ -f "$MEMORY_FILE" ] && stat -f '%m %z' "$MEMORY_FILE" 2>/dev/null
+    if [ -d "$GOTCHAS_DIR" ]; then
+      for f in "$GOTCHAS_DIR"/*.md; do
+        [ -e "$f" ] || continue
+        stat -f '%N %m %z' "$f" 2>/dev/null
+      done
+    fi
+  } | md5 -q 2>/dev/null || echo "$RANDOM"
+}
+
+# 활성 에이전트 결정: 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 대신 커서 홈 + 화면 끝까지 지우기 — 깜빡임 최소화
+  printf '\033[H\033[2J\033[3J'
+  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
+  sig=$(compute_signature)
+  if [ "$sig" != "$LAST_SIG" ]; then
+    render
+    LAST_SIG="$sig"
+  fi
+  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