@walwal-harness/cli 3.4.0 → 3.6.0

package/assets/templates/HARNESS.md

@@ -143,8 +143,39 @@ pending → draft → reviewed → approved
 | 파일 | 역할 |
 |------|------|
 | `.harness/progress.json` | 기계 판독 상태 (현재 에이전트, 파이프라인, 실패 정보) |
-| `.harness/progress.log` | 사람 판독 히스토리 (append-only) |
-| `.harness/handoff.json` | 세션 전환 문서 (prompt, model, thinking_mode, artifacts, regression) |
+| `.harness/progress.log` | 사람 판독 히스토리 (append-only, 전체) |
+| `.harness/handoff.json` | 세션 전환 문서 (prompt, model, thinking_mode, artifacts) |
+| `.harness/actions/audit.log` | Sprint cycle 단위 실행 추적 (Planner→Eval 통과) |
+
+### Audit Log
+
+1 sprint cycle(Planner/Dispatcher 시작 → Eval 통과) 단위의 상세 실행 추적입니다.
+
+```
+# 예시:
+TIMESTAMP            | AGENT          | ACTION   | STATUS   | TARGET                         | DETAIL
+2026-04-09T14:30:00Z | planner        | plan     | start    | plan.md                        | Sprint 1 설계 시작
+2026-04-09T14:35:00Z | planner        | plan     | complete | api-contract.json              | 3 endpoints, 2 services
+2026-04-09T14:35:01Z | planner        | handoff  | complete | →gen-backend                   |
+2026-04-09T14:36:00Z | system         | gate     | pass     | pre-eval                       | gen-backend
+2026-04-09T14:40:00Z | gen-backend    | develop  | start    | apps/service-user/             | User CRUD 구현
+2026-04-09T14:50:00Z | gen-backend    | develop  | complete | apps/service-user/             | 4 endpoints
+2026-04-09T14:50:01Z | gen-backend    | handoff  | complete | →eval-functional               |
+2026-04-09T14:55:00Z | eval-func      | review   | start    | POST /api/auth/register        | AC-001~003 검증
+2026-04-09T14:58:00Z | eval-func      | review   | fail     | POST /api/auth/register        | 409→400 contract 불일치
+2026-04-09T14:58:01Z | eval-func      | handoff  | complete | →gen-backend                   | Re-Generate
+```
+
+**라이프사이클**: 새 Planner/Dispatcher 사이클 시작 시 이전 로그는 archive로 이동, 새 로그 시작.
+
+**에이전트 기록 의무**: 모든 에이전트는 세션 중 주요 작업의 시작/완료를 audit에 기록해야 합니다.
+
+```bash
+# 에이전트 스킬에서 호출:
+source scripts/lib/harness-audit.sh && init_audit .
+audit_log "gen-backend" "develop" "start" "apps/service-user/" "User CRUD 구현"
+audit_log "gen-backend" "develop" "complete" "apps/service-user/" "4 endpoints 완료"
+```
 
 ### 실행 방법
 

package/assets/templates/config.json

@@ -337,6 +337,23 @@
     "progress_state": ".harness/progress.json",
     "progress_log": ".harness/progress.log"
   },
+  "audit": {
+    "comment": "Audit log — 1 sprint cycle 단위의 실행 추적. Planner/Dispatcher 시작 시 리셋.",
+    "file": ".harness/actions/audit.log",
+    "lifecycle": "planner_to_eval_pass",
+    "reset_on": ["planner", "dispatcher"],
+    "archive_previous": true,
+    "format": "TIMESTAMP | AGENT | ACTION | STATUS | TARGET | DETAIL",
+    "actions": {
+      "develop": "코드 생성/수정 (Generator)",
+      "review": "검수/평가 (Evaluator)",
+      "handoff": "에이전트 전환",
+      "plan": "설계/계획 (Planner)",
+      "gate": "자동 게이트 체크 (system)",
+      "escalate": "에스컬레이션 (system)"
+    },
+    "statuses": ["start", "complete", "fail", "pass", "skip", "warn"]
+  },
   "conventions": {
     "comment": "CONVENTIONS.md — 사용자가 자유 형식으로 작성하는 프로젝트 컨벤션. 모든 에이전트가 세션 시작 시 직접 읽음. Gotcha/AGENTS.md에 복사하지 않음.",
     "file": "CONVENTIONS.md",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@walwal-harness/cli",
-  "version": "3.4.0",
+  "version": "3.6.0",
   "description": "Production harness for AI agent engineering — Planner, Generator(BE/FE), Evaluator(Func/Visual), optional Brainstormer (requirements refinement). Supports React and Flutter FE stacks.",
   "bin": {
     "walwal-harness": "bin/init.js"

package/scripts/harness-dashboard.sh

@@ -0,0 +1,179 @@
+#!/bin/bash
+# harness-dashboard.sh — Panel 1: 실시간 대시보드
+# progress.json + feature-list.json 을 2초 간격으로 시각화
+# Usage: bash scripts/harness-dashboard.sh [project-root]
+
+set -euo 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 "[dashboard] .harness/ not found. Pass project root as argument."
+    exit 1
+  }
+fi
+
+PROGRESS="$PROJECT_ROOT/.harness/progress.json"
+FEATURES="$PROJECT_ROOT/.harness/actions/feature-list.json"
+
+# ── ANSI helpers ──
+BOLD="\033[1m"
+DIM="\033[2m"
+GREEN="\033[32m"
+YELLOW="\033[33m"
+RED="\033[31m"
+CYAN="\033[36m"
+RESET="\033[0m"
+
+render_header() {
+  local now
+  now=$(date +"%H:%M:%S")
+  local project_name
+  project_name=$(jq -r '.project_name // "Unknown"' "$PROGRESS" 2>/dev/null)
+
+  echo -e "${BOLD}╔══════════════════════════════════════╗${RESET}"
+  echo -e "${BOLD}║  HARNESS DASHBOARD                   ║${RESET}"
+  echo -e "${BOLD}╚══════════════════════════════════════╝${RESET}"
+  echo -e "  ${DIM}${project_name}  |  Updated: ${now}${RESET}"
+  echo ""
+}
+
+render_sprint_overview() {
+  if [ ! -f "$PROGRESS" ]; then
+    echo -e "  ${DIM}(waiting for harness init...)${RESET}"
+    return
+  fi
+
+  local pipeline sprint_num sprint_status current_agent agent_status retry_count
+  pipeline=$(jq -r '.pipeline // "?"' "$PROGRESS")
+  sprint_num=$(jq -r '.sprint.number // 0' "$PROGRESS")
+  sprint_status=$(jq -r '.sprint.status // "init"' "$PROGRESS")
+  current_agent=$(jq -r '.current_agent // "none"' "$PROGRESS")
+  agent_status=$(jq -r '.agent_status // "pending"' "$PROGRESS")
+  retry_count=$(jq -r '.sprint.retry_count // 0' "$PROGRESS")
+
+  # Status color
+  local status_color="$RESET"
+  case "$agent_status" in
+    running)   status_color="$GREEN" ;;
+    completed) status_color="$CYAN" ;;
+    failed)    status_color="$RED" ;;
+    blocked)   status_color="$RED" ;;
+    *)         status_color="$YELLOW" ;;
+  esac
+
+  echo -e "  ${BOLD}Pipeline${RESET}  ${pipeline}"
+  echo -e "  ${BOLD}Sprint${RESET}    ${sprint_num} (${sprint_status})"
+  echo -e "  ${BOLD}Agent${RESET}     ${status_color}${current_agent} [${agent_status}]${RESET}"
+  if [ "$retry_count" -gt 0 ]; then
+    echo -e "  ${BOLD}Retries${RESET}   ${RED}${retry_count}${RESET}"
+  fi
+  echo ""
+}
+
+render_sprint_map() {
+  if [ ! -f "$PROGRESS" ]; then return; fi
+
+  local sprint_keys
+  sprint_keys=$(jq -r '.sprint_progress // {} | keys[]' "$PROGRESS" 2>/dev/null | sort -n)
+  if [ -z "$sprint_keys" ]; then return; fi
+
+  echo -e "  ${BOLD}Sprint Map${RESET}"
+
+  while IFS= read -r s; do
+    local status features_csv notes
+    status=$(jq -r ".sprint_progress[\"${s}\"].status // \"pending\"" "$PROGRESS")
+    features_csv=$(jq -r ".sprint_progress[\"${s}\"].features // [] | join(\",\")" "$PROGRESS")
+    notes=$(jq -r ".sprint_progress[\"${s}\"].notes // \"\"" "$PROGRESS")
+
+    # Status icon
+    local icon="○"
+    case "$status" in
+      completed)   icon="●" ;;
+      in_progress) icon="◐" ;;
+      scaffolded)  icon="◑" ;;
+      pending)     icon="○" ;;
+    esac
+
+    # Count features
+    local feat_count
+    feat_count=$(jq ".sprint_progress[\"${s}\"].features // [] | length" "$PROGRESS")
+
+    # Truncate notes
+    if [ ${#notes} -gt 40 ]; then
+      notes="${notes:0:38}.."
+    fi
+
+    printf "  %s S%-2s  %2d feat  %-12s %s\n" "$icon" "$s" "$feat_count" "$status" "$notes"
+  done <<< "$sprint_keys"
+
+  echo ""
+}
+
+render_build_status() {
+  if [ ! -f "$PROGRESS" ]; then return; fi
+
+  local build_status tsc_status routes_total last_build
+  build_status=$(jq -r '.build.build_status // "unknown"' "$PROGRESS" 2>/dev/null)
+  tsc_status=$(jq -r '.build.tsc_status // "unknown"' "$PROGRESS" 2>/dev/null)
+  routes_total=$(jq -r '.build.routes_total // 0' "$PROGRESS" 2>/dev/null)
+  last_build=$(jq -r '.build.last_build // "n/a"' "$PROGRESS" 2>/dev/null)
+
+  if [ "$build_status" = "null" ] || [ "$build_status" = "unknown" ]; then return; fi
+
+  local build_color="$GREEN"
+  if [ "$build_status" != "passing" ]; then build_color="$RED"; fi
+  local tsc_color="$GREEN"
+  if [ "$tsc_status" != "clean" ]; then tsc_color="$RED"; fi
+
+  echo -e "  ${BOLD}Build${RESET}"
+  echo -e "  Build: ${build_color}${build_status}${RESET}  |  TSC: ${tsc_color}${tsc_status}${RESET}  |  Routes: ${routes_total}"
+  echo ""
+}
+
+render_failure_info() {
+  if [ ! -f "$PROGRESS" ]; then return; fi
+
+  local failure_agent
+  failure_agent=$(jq -r '.failure.agent // empty' "$PROGRESS" 2>/dev/null)
+
+  if [ -n "$failure_agent" ] && [ "$failure_agent" != "null" ]; then
+    local failure_loc failure_msg
+    failure_loc=$(jq -r '.failure.location // ""' "$PROGRESS")
+    failure_msg=$(jq -r '.failure.message // ""' "$PROGRESS")
+
+    echo -e "  ${RED}${BOLD}╔═ FAILURE ═══════════════════════════╗${RESET}"
+    echo -e "  ${RED}  Agent: ${failure_agent}${RESET}"
+    echo -e "  ${RED}  Where: ${failure_loc}${RESET}"
+    if [ -n "$failure_msg" ] && [ "$failure_msg" != "null" ]; then
+      echo -e "  ${RED}  ${failure_msg}${RESET}"
+    fi
+    echo -e "  ${RED}${BOLD}╚════════════════════════════════════╝${RESET}"
+    echo ""
+  fi
+}
+
+# ── Main Loop ──
+while true; do
+  clear
+  render_header
+  render_sprint_overview
+  render_build_status
+  render_failure_info
+  render_sprint_map
+
+  # Feature progress (reuse existing lib)
+  if [ -f "$FEATURES" ]; then
+    render_progress "$PROJECT_ROOT" 2>/dev/null
+  fi
+
+  # Agent sequence bar
+  render_agent_bar "$PROJECT_ROOT" 2>/dev/null
+  echo ""
+
+  echo -e "  ${DIM}Refreshing every 2s  |  Ctrl+C to exit${RESET}"
+  sleep 2
+done

package/scripts/harness-eval-watcher.sh

@@ -0,0 +1,230 @@
+#!/bin/bash
+# harness-eval-watcher.sh — Panel 3: Evaluation 결과 Summary 리뷰
+# evaluation-*.md 파일 변경 감지 → 요약 출력 (또는 claude -p 호출)
+# Usage: bash scripts/harness-eval-watcher.sh [project-root] [--ai]
+#   --ai  evaluation 완료 시 claude -p 로 AI 요약 생성 (API 비용 발생)
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+PROJECT_ROOT="${1:-}"
+USE_AI=false
+for arg in "$@"; do
+  if [ "$arg" = "--ai" ]; then USE_AI=true; fi
+done
+
+if [ -z "$PROJECT_ROOT" ] || [ "$PROJECT_ROOT" = "--ai" ]; then
+  source "$SCRIPT_DIR/lib/harness-render-progress.sh"
+  PROJECT_ROOT="$(resolve_harness_root ".")" || {
+    echo "[eval-watcher] .harness/ not found. Pass project root as argument."
+    exit 1
+  }
+fi
+
+PROGRESS="$PROJECT_ROOT/.harness/progress.json"
+EVAL_FUNC="$PROJECT_ROOT/.harness/actions/evaluation-functional.md"
+EVAL_VISUAL="$PROJECT_ROOT/.harness/actions/evaluation-visual.md"
+
+# ── ANSI helpers ──
+BOLD="\033[1m"
+DIM="\033[2m"
+GREEN="\033[32m"
+YELLOW="\033[33m"
+RED="\033[31m"
+CYAN="\033[36m"
+RESET="\033[0m"
+
+LAST_FUNC_HASH=""
+LAST_VISUAL_HASH=""
+EVAL_COUNT=0
+
+print_header() {
+  echo -e "${BOLD}╔══════════════════════════════════════╗${RESET}"
+  echo -e "${BOLD}║  EVALUATION REVIEW                   ║${RESET}"
+  echo -e "${BOLD}╚══════════════════════════════════════╝${RESET}"
+  echo ""
+}
+
+file_hash() {
+  if [ -f "$1" ]; then
+    md5 -q "$1" 2>/dev/null || md5sum "$1" 2>/dev/null | awk '{print $1}' || echo ""
+  else
+    echo ""
+  fi
+}
+
+# ── Extract eval summary from markdown ──
+extract_eval_summary() {
+  local file="$1" type="$2"
+
+  if [ ! -f "$file" ]; then return; fi
+
+  EVAL_COUNT=$((EVAL_COUNT + 1))
+  local now
+  now=$(date +"%H:%M:%S")
+
+  echo -e "  ${BOLD}═══ ${type} Evaluation #${EVAL_COUNT} ═══${RESET}  ${DIM}(${now})${RESET}"
+  echo ""
+
+  # Extract Verdict (PASS/FAIL)
+  local verdict
+  verdict=$(grep -i "verdict\|result\|판정" "$file" | head -3)
+  if [ -n "$verdict" ]; then
+    if echo "$verdict" | grep -qi "PASS"; then
+      echo -e "  ${GREEN}${BOLD}VERDICT: PASS${RESET}"
+    elif echo "$verdict" | grep -qi "FAIL"; then
+      echo -e "  ${RED}${BOLD}VERDICT: FAIL${RESET}"
+    else
+      echo -e "  ${YELLOW}VERDICT: ${verdict}${RESET}"
+    fi
+    echo ""
+  fi
+
+  # Extract Score
+  local score_line
+  score_line=$(grep -iE "score|점수|weighted|가중" "$file" | head -3)
+  if [ -n "$score_line" ]; then
+    echo -e "  ${BOLD}Score${RESET}"
+    echo "$score_line" | while IFS= read -r line; do
+      # Color by score value
+      local num
+      num=$(echo "$line" | grep -oE '[0-9]+\.[0-9]+' | head -1)
+      if [ -n "$num" ]; then
+        local int_part
+        int_part=$(echo "$num" | cut -d. -f1)
+        if [ "${int_part:-0}" -ge 3 ] || ([ "${int_part:-0}" -eq 2 ] && [ "$(echo "$num >= 2.80" | bc 2>/dev/null)" = "1" ]); then
+          echo -e "    ${GREEN}${line}${RESET}"
+        else
+          echo -e "    ${RED}${line}${RESET}"
+        fi
+      else
+        echo "    $line"
+      fi
+    done
+    echo ""
+  fi
+
+  # Extract individual rubric items (R1-R5 or V1-V5)
+  local rubric_lines
+  rubric_lines=$(grep -E "^[|#].*[RV][1-5]" "$file" | head -10)
+  if [ -n "$rubric_lines" ]; then
+    echo -e "  ${BOLD}Rubric${RESET}"
+    echo "$rubric_lines" | while IFS= read -r line; do
+      echo "    $line"
+    done
+    echo ""
+  fi
+
+  # Extract FAIL reasons
+  local fail_lines
+  fail_lines=$(grep -iE "fail|실패|regression|불일치|위반" "$file" | head -5)
+  if [ -n "$fail_lines" ]; then
+    echo -e "  ${RED}${BOLD}Issues${RESET}"
+    echo "$fail_lines" | while IFS= read -r line; do
+      echo -e "    ${RED}• ${line}${RESET}"
+    done
+    echo ""
+  fi
+
+  # Extract action items / recommendations
+  local action_lines
+  action_lines=$(grep -iE "recommend|action|수정|개선|필요|re-generate" "$file" | head -5)
+  if [ -n "$action_lines" ]; then
+    echo -e "  ${YELLOW}${BOLD}Actions${RESET}"
+    echo "$action_lines" | while IFS= read -r line; do
+      echo -e "    ${YELLOW}→ ${line}${RESET}"
+    done
+    echo ""
+  fi
+
+  echo -e "  ${DIM}─────────────────────────────────────${RESET}"
+  echo ""
+}
+
+# ── AI Summary (optional) ──
+generate_ai_summary() {
+  local file="$1" type="$2"
+
+  if [ "$USE_AI" != true ]; then return; fi
+  if ! command -v claude &>/dev/null; then
+    echo -e "  ${DIM}(claude CLI not found — skipping AI summary)${RESET}"
+    return
+  fi
+
+  echo -e "  ${CYAN}Generating AI summary...${RESET}"
+
+  local summary
+  summary=$(claude -p "다음 ${type} Evaluation 문서를 3줄 이내로 요약해줘. 핵심 결과(PASS/FAIL), 주요 문제점, 다음 액션을 포함:
+
+$(cat "$file")" --output-format text 2>/dev/null || echo "(AI summary failed)")
+
+  echo -e "  ${CYAN}${BOLD}AI Summary:${RESET}"
+  echo "$summary" | while IFS= read -r line; do
+    echo -e "    ${CYAN}${line}${RESET}"
+  done
+  echo ""
+}
+
+# ── Main ──
+print_header
+
+# Show existing evals on startup
+if [ -f "$EVAL_FUNC" ]; then
+  echo -e "  ${DIM}Found existing functional evaluation${RESET}"
+  extract_eval_summary "$EVAL_FUNC" "Functional"
+  LAST_FUNC_HASH=$(file_hash "$EVAL_FUNC")
+fi
+
+if [ -f "$EVAL_VISUAL" ]; then
+  echo -e "  ${DIM}Found existing visual evaluation${RESET}"
+  extract_eval_summary "$EVAL_VISUAL" "Visual"
+  LAST_VISUAL_HASH=$(file_hash "$EVAL_VISUAL")
+fi
+
+if [ -z "$LAST_FUNC_HASH" ] && [ -z "$LAST_VISUAL_HASH" ]; then
+  echo -e "  ${DIM}Waiting for evaluation files...${RESET}"
+  echo -e "  ${DIM}  ${EVAL_FUNC}${RESET}"
+  echo -e "  ${DIM}  ${EVAL_VISUAL}${RESET}"
+  echo ""
+fi
+
+echo -e "  ${DIM}Watching for changes every 3s  |  Ctrl+C to exit${RESET}"
+if [ "$USE_AI" = true ]; then
+  echo -e "  ${CYAN}AI summary enabled (claude -p)${RESET}"
+fi
+echo ""
+
+# ── Poll for changes ──
+while true; do
+  # Check functional eval
+  local_func_hash=$(file_hash "$EVAL_FUNC")
+  if [ "$local_func_hash" != "$LAST_FUNC_HASH" ] && [ -n "$local_func_hash" ]; then
+    LAST_FUNC_HASH="$local_func_hash"
+    extract_eval_summary "$EVAL_FUNC" "Functional"
+    generate_ai_summary "$EVAL_FUNC" "Functional"
+  fi
+
+  # Check visual eval
+  local_visual_hash=$(file_hash "$EVAL_VISUAL")
+  if [ "$local_visual_hash" != "$LAST_VISUAL_HASH" ] && [ -n "$local_visual_hash" ]; then
+    LAST_VISUAL_HASH="$local_visual_hash"
+    extract_eval_summary "$EVAL_VISUAL" "Visual"
+    generate_ai_summary "$EVAL_VISUAL" "Visual"
+  fi
+
+  # Check agent status for eval-related transitions
+  if [ -f "$PROGRESS" ]; then
+    local agent
+    agent=$(jq -r '.current_agent // "none"' "$PROGRESS" 2>/dev/null)
+    local status
+    status=$(jq -r '.agent_status // "pending"' "$PROGRESS" 2>/dev/null)
+
+    if [[ "$agent" == evaluator-* ]] && [ "$status" = "running" ]; then
+      # Show that evaluator is active
+      :
+    fi
+  fi
+
+  sleep 3
+done

package/scripts/harness-monitor.sh

@@ -0,0 +1,193 @@
+#!/bin/bash
+# harness-monitor.sh — Panel 2: Task & Agent Lifecycle 모니터링
+# audit.log 스트리밍 + progress.json 변경 감지
+# Usage: bash scripts/harness-monitor.sh [project-root]
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+PROJECT_ROOT="${1:-}"
+if [ -z "$PROJECT_ROOT" ]; then
+  source "$SCRIPT_DIR/lib/harness-render-progress.sh"
+  PROJECT_ROOT="$(resolve_harness_root ".")" || {
+    echo "[monitor] .harness/ not found. Pass project root as argument."
+    exit 1
+  }
+fi
+
+PROGRESS="$PROJECT_ROOT/.harness/progress.json"
+AUDIT_LOG="$PROJECT_ROOT/.harness/actions/audit.log"
+HANDOFF="$PROJECT_ROOT/.harness/handoff.json"
+
+# ── ANSI helpers ──
+BOLD="\033[1m"
+DIM="\033[2m"
+GREEN="\033[32m"
+YELLOW="\033[33m"
+RED="\033[31m"
+CYAN="\033[36m"
+MAGENTA="\033[35m"
+RESET="\033[0m"
+
+LAST_AGENT=""
+LAST_STATUS=""
+LAST_SPRINT=""
+EVENT_COUNT=0
+
+print_event() {
+  local ts="$1" icon="$2" color="$3" msg="$4"
+  EVENT_COUNT=$((EVENT_COUNT + 1))
+  echo -e "  ${DIM}${ts}${RESET}  ${color}${icon}${RESET}  ${msg}"
+}
+
+# ── Header ──
+print_header() {
+  echo -e "${BOLD}╔══════════════════════════════════════╗${RESET}"
+  echo -e "${BOLD}║  AGENT LIFECYCLE MONITOR             ║${RESET}"
+  echo -e "${BOLD}╚══════════════════════════════════════╝${RESET}"
+  echo ""
+}
+
+# ── Detect agent transitions from progress.json ──
+check_transitions() {
+  if [ ! -f "$PROGRESS" ]; then return; fi
+
+  local agent status sprint
+  agent=$(jq -r '.current_agent // "none"' "$PROGRESS" 2>/dev/null)
+  status=$(jq -r '.agent_status // "pending"' "$PROGRESS" 2>/dev/null)
+  sprint=$(jq -r '.sprint.number // 0' "$PROGRESS" 2>/dev/null)
+
+  local now
+  now=$(date +"%H:%M:%S")
+
+  # Sprint change
+  if [ "$sprint" != "$LAST_SPRINT" ] && [ -n "$LAST_SPRINT" ]; then
+    print_event "$now" ">>>" "$MAGENTA" "${BOLD}Sprint ${sprint} started${RESET}"
+    echo ""
+  fi
+
+  # Agent change
+  if [ "$agent" != "$LAST_AGENT" ] && [ -n "$LAST_AGENT" ]; then
+    if [ "$LAST_AGENT" != "none" ] && [ "$LAST_AGENT" != "null" ]; then
+      print_event "$now" " ✓ " "$GREEN" "${LAST_AGENT} → ${BOLD}done${RESET}"
+    fi
+    if [ "$agent" != "none" ] && [ "$agent" != "null" ]; then
+      print_event "$now" " ▶ " "$CYAN" "${BOLD}${agent}${RESET} started"
+
+      # Show handoff context if available
+      if [ -f "$HANDOFF" ]; then
+        local from focus
+        from=$(jq -r '.from // empty' "$HANDOFF" 2>/dev/null)
+        focus=$(jq -r '.focus_features // [] | join(", ")' "$HANDOFF" 2>/dev/null)
+        if [ -n "$from" ] && [ "$from" != "null" ]; then
+          echo -e "         ${DIM}handoff from: ${from}${RESET}"
+        fi
+        if [ -n "$focus" ] && [ "$focus" != "null" ]; then
+          echo -e "         ${DIM}focus: ${focus}${RESET}"
+        fi
+      fi
+    fi
+  fi
+
+  # Status change (same agent)
+  if [ "$agent" = "$LAST_AGENT" ] && [ "$status" != "$LAST_STATUS" ] && [ -n "$LAST_STATUS" ]; then
+    local status_color="$RESET"
+    local status_icon="•"
+    case "$status" in
+      running)   status_color="$GREEN";  status_icon=" ▶ " ;;
+      completed) status_color="$CYAN";   status_icon=" ✓ " ;;
+      failed)    status_color="$RED";    status_icon=" ✗ " ;;
+      blocked)   status_color="$RED";    status_icon=" ! " ;;
+      pending)   status_color="$YELLOW"; status_icon=" … " ;;
+    esac
+    print_event "$now" "$status_icon" "$status_color" "${agent} → ${BOLD}${status}${RESET}"
+
+    # Show failure detail
+    if [ "$status" = "failed" ]; then
+      local fail_msg
+      fail_msg=$(jq -r '.failure.message // empty' "$PROGRESS" 2>/dev/null)
+      if [ -n "$fail_msg" ] && [ "$fail_msg" != "null" ]; then
+        echo -e "         ${RED}${fail_msg}${RESET}"
+      fi
+    fi
+  fi
+
+  LAST_AGENT="$agent"
+  LAST_STATUS="$status"
+  LAST_SPRINT="$sprint"
+}
+
+# ── Stream audit.log new lines ──
+stream_audit() {
+  if [ ! -f "$AUDIT_LOG" ]; then return; fi
+
+  # Use tail -f in background, parse each new line
+  tail -n 0 -f "$AUDIT_LOG" 2>/dev/null | while IFS= read -r line; do
+    # Skip comments/headers
+    if [[ "$line" == "#"* ]] || [[ -z "$line" ]]; then continue; fi
+
+    # Parse: TIMESTAMP | AGENT | ACTION | STATUS | TARGET | DETAIL
+    local ts agent action status target detail
+    ts=$(echo "$line" | awk -F'|' '{gsub(/^ +| +$/,"",$1); print $1}')
+    agent=$(echo "$line" | awk -F'|' '{gsub(/^ +| +$/,"",$2); print $2}')
+    action=$(echo "$line" | awk -F'|' '{gsub(/^ +| +$/,"",$3); print $3}')
+    status=$(echo "$line" | awk -F'|' '{gsub(/^ +| +$/,"",$4); print $4}')
+    target=$(echo "$line" | awk -F'|' '{gsub(/^ +| +$/,"",$5); print $5}')
+    detail=$(echo "$line" | awk -F'|' '{gsub(/^ +| +$/,"",$6); print $6}')
+
+    # Color by status
+    local color="$RESET" icon="•"
+    case "$status" in
+      start)    color="$CYAN";   icon="▶" ;;
+      complete) color="$GREEN";  icon="✓" ;;
+      fail)     color="$RED";    icon="✗" ;;
+      pass)     color="$GREEN";  icon="✓" ;;
+      skip)     color="$DIM";    icon="–" ;;
+    esac
+
+    # Short timestamp (HH:MM:SS from ISO)
+    local short_ts
+    short_ts=$(echo "$ts" | grep -oE '[0-9]{2}:[0-9]{2}:[0-9]{2}' || echo "$ts")
+
+    echo -e "  ${DIM}${short_ts}${RESET}  ${color}${icon}${RESET}  ${BOLD}${agent}${RESET} ${action} ${target} ${DIM}${detail}${RESET}"
+  done &
+  AUDIT_TAIL_PID=$!
+}
+
+# ── Cleanup ──
+cleanup() {
+  if [ -n "${AUDIT_TAIL_PID:-}" ]; then
+    kill "$AUDIT_TAIL_PID" 2>/dev/null || true
+  fi
+  exit 0
+}
+trap cleanup EXIT INT TERM
+
+# ── Main ──
+print_header
+
+# Initialize state
+if [ -f "$PROGRESS" ]; then
+  LAST_AGENT=$(jq -r '.current_agent // "none"' "$PROGRESS" 2>/dev/null)
+  LAST_STATUS=$(jq -r '.agent_status // "pending"' "$PROGRESS" 2>/dev/null)
+  LAST_SPRINT=$(jq -r '.sprint.number // 0' "$PROGRESS" 2>/dev/null)
+fi
+
+# Show existing history
+if [ -f "$PROGRESS" ]; then
+  echo -e "  ${BOLD}History${RESET}"
+  jq -r '.history // [] | .[] | "  \(.timestamp)  \(.agent) — \(.action): \(.detail)"' "$PROGRESS" 2>/dev/null
+  echo ""
+  echo -e "  ${DIM}── Live events below ──${RESET}"
+  echo ""
+fi
+
+# Start audit log streaming
+stream_audit
+
+# Poll progress.json for transitions
+while true; do
+  check_transitions
+  sleep 2
+done

package/scripts/harness-next.sh

@@ -7,6 +7,7 @@ set -e
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 source "$SCRIPT_DIR/lib/harness-render-progress.sh"
 source "$SCRIPT_DIR/lib/harness-guardrail.sh"
+source "$SCRIPT_DIR/lib/harness-audit.sh"
 
 # ─────────────────────────────────────────
 # Resolve project root
@@ -24,6 +25,9 @@ HANDOFF="$PROJECT_ROOT/.harness/handoff.json"
 
 check_jq || exit 1
 
+# Initialize audit log
+init_audit "$PROJECT_ROOT"
+
 if [ ! -f "$PROGRESS" ]; then
   echo "[harness] ERROR: progress.json not found" >&2
   echo "  Run 'npx walwal-harness --force' to reinitialize." >&2
@@ -277,15 +281,25 @@ verify_artifact_prerequisites() {
 # Runtime Guardrail — 파일 소유권 검증
 # ─────────────────────────────────────────
 if [ "$agent_status" = "completed" ]; then
-  verify_file_ownership "$PROJECT_ROOT" || true
+  audit_log "$current_agent" "develop" "complete" "" "agent completed"
+  verify_file_ownership "$PROJECT_ROOT" || audit_gate "file-ownership" "warn" "boundary violation detected"
 fi
 
 # ─────────────────────────────────────────
 # Run Pre-Eval Gate (if applicable)
 # ─────────────────────────────────────────
 if [ "$agent_status" = "completed" ]; then
-  run_pre_eval_gate "$next_agent" || true
-  verify_artifact_prerequisites "$next_agent" || true
+  audit_gate "pre-eval" "start" "$next_agent"
+  if run_pre_eval_gate "$next_agent"; then
+    audit_gate "pre-eval" "pass" "$next_agent"
+  else
+    audit_gate "pre-eval" "fail" "rerouted to $current_agent"
+  fi
+  if verify_artifact_prerequisites "$next_agent"; then
+    audit_gate "artifact-prereq" "pass" "$next_agent"
+  else
+    audit_gate "artifact-prereq" "fail" "$next_agent"
+  fi
 fi
 
 # ─────────────────────────────────────────
@@ -303,6 +317,7 @@ if [ "$next_agent" != "null" ] && [ "$next_agent" != "archive" ] && [ "$agent_st
   escalate_after=$(jq -r '.flow.escalate_to_planner_after // 3' "$CONFIG" 2>/dev/null || echo 3)
   if [ "$retry_count" -ge "$escalate_after" ] && [ "$sprint_status" = "failed" ] && [ "$next_agent" != "planner" ]; then
     echo "  ⚠ Escalation: ${retry_count}회 실패 — Planner에게 scope 축소/접근 변경 요청"
+    audit_log "system" "escalate" "start" "→planner" "retry ${retry_count}회 초과"
     next_agent="planner"
     jq --arg msg "Escalated after ${retry_count} failures. Planner must review scope or approach." \
        '.next_agent = "planner" |
@@ -442,7 +457,10 @@ if [ "$next_agent" != "null" ] && [ "$next_agent" != "archive" ] && [ "$agent_st
       timestamp: $timestamp
     }' > "$HANDOFF"
 
+  audit_handoff "${current_agent:-dispatcher}" "$next_agent" "complete"
+
 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" \

package/scripts/harness-session-start.sh

@@ -1,17 +1,17 @@
 #!/bin/bash
 # harness-session-start.sh — SessionStart 훅
 # 새 세션 시작 시 자동으로:
-#   1) 이전 에이전트가 completed이면 harness-next.sh를 실행하여 게이트 체크 + handoff 생성
-#   2) handoff.json이 있으면 다음 에이전트 안내
-#   3) statusline이 상시 상태를 표시하므로 여기서는 핵심 안내만 출력
-#
-# 사용자가 수동으로 harness-next.sh를 실행할 필요가 없도록 자동화.
+#   1) 이전 에이전트가 completed이면 harness-next.sh 실행 (게이트 + handoff)
+#   2) Planner/Dispatcher 사이클이면 audit 리셋
+#   3) 다음 에이전트 안내 출력
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 LIB="$SCRIPT_DIR/lib/harness-render-progress.sh"
+AUDIT_LIB="$SCRIPT_DIR/lib/harness-audit.sh"
 
 if [ ! -f "$LIB" ]; then exit 0; fi
 source "$LIB"
+[ -f "$AUDIT_LIB" ] && source "$AUDIT_LIB"
 command -v jq &>/dev/null || exit 0
 
 PROJECT_ROOT="$(resolve_harness_root "." 2>/dev/null)" || exit 0
@@ -21,6 +21,7 @@ HANDOFF="$PROJECT_ROOT/.harness/handoff.json"
 [ -f "$PROGRESS" ] || exit 0
 
 sprint_status=$(jq -r '.sprint.status // "init"' "$PROGRESS" 2>/dev/null)
+sprint_num=$(jq -r '.sprint.number // 0' "$PROGRESS" 2>/dev/null)
 current_agent=$(jq -r '.current_agent // "none"' "$PROGRESS" 2>/dev/null)
 next_agent=$(jq -r '.next_agent // "none"' "$PROGRESS" 2>/dev/null)
 agent_status=$(jq -r '.agent_status // "pending"' "$PROGRESS" 2>/dev/null)
@@ -34,14 +35,21 @@ if [ "$sprint_status" = "init" ]; then
 fi
 
 # ─────────────────────────────────────────
-# 이전 에이전트가 completed → 자동으로 harness-next 실행
-# (게이트 체크, 아티팩트 검증, handoff.json 생성)
+# Audit lifecycle: Planner/Dispatcher 시작 시 리셋
+# ─────────────────────────────────────────
+init_audit "$PROJECT_ROOT"
+if [ "$next_agent" = "planner" ] || [ "$next_agent" = "dispatcher" ]; then
+  # 새 사이클 — 이전 audit을 archive로 이동하고 새로 시작
+  reset_audit "$PROJECT_ROOT" "$sprint_num"
+  audit_log "system" "cycle" "start" "sprint-${sprint_num}" "new plan/dispatch cycle"
+fi
+
+# ─────────────────────────────────────────
+# 이전 에이전트가 completed/failed → 자동 전환
 # ─────────────────────────────────────────
 if [ "$agent_status" = "completed" ] || [ "$agent_status" = "failed" ]; then
-  # harness-next.sh를 백그라운드로 실행하면 안 됨 — 결과가 필요
   bash "$SCRIPT_DIR/harness-next.sh" "$PROJECT_ROOT" 2>/dev/null
 
-  # harness-next.sh가 progress.json과 handoff.json을 업데이트했으므로 다시 읽기
   next_agent=$(jq -r '.next_agent // "none"' "$PROGRESS" 2>/dev/null)
   agent_status=$(jq -r '.agent_status // "pending"' "$PROGRESS" 2>/dev/null)
 fi
@@ -53,7 +61,6 @@ if [ "$agent_status" = "blocked" ]; then
   echo "# Harness BLOCKED — retry limit reached, user intervention required"
 
 elif [ -f "$HANDOFF" ] && [ "$next_agent" != "none" ] && [ "$next_agent" != "null" ]; then
-  # handoff.json에서 모델/모드 정보 읽기
   handoff_model=$(jq -r '.model // "opus"' "$HANDOFF" 2>/dev/null)
   handoff_thinking=$(jq -r '.thinking_mode // empty' "$HANDOFF" 2>/dev/null)
 

package/scripts/harness-tmux.sh

@@ -0,0 +1,121 @@
+#!/bin/bash
+# harness-tmux.sh — tmux 4-pane 레이아웃 자동 구성
+#
+# ┌──────────────────────┬──────────────────────┐
+# │                      │ Panel 1: Dashboard   │
+# │  Main Terminal       ├──────────────────────┤
+# │  (claude 대화형)      │ Panel 2: Monitor     │
+# │                      ├──────────────────────┤
+# │                      │ Panel 3: Eval Review │
+# └──────────────────────┴──────────────────────┘
+#
+# Usage:
+#   bash scripts/harness-tmux.sh [project-root]
+#   bash scripts/harness-tmux.sh /path/to/project --ai   (AI eval summary 활성화)
+#
+# Options:
+#   --ai        Panel 3에서 claude -p 로 AI 요약 생성 (API 비용 발생)
+#   --detach    세션 생성 후 attach 하지 않음
+#   --kill      기존 harness-studio 세션 종료
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SESSION_NAME="harness-studio"
+
+PROJECT_ROOT=""
+USE_AI=""
+DETACH=false
+KILL=false
+
+for arg in "$@"; do
+  case "$arg" in
+    --ai)     USE_AI="--ai" ;;
+    --detach) DETACH=true ;;
+    --kill)
+      tmux kill-session -t "$SESSION_NAME" 2>/dev/null && echo "Session '$SESSION_NAME' killed." || echo "No session to kill."
+      exit 0
+      ;;
+    *)
+      if [ -d "$arg" ]; then PROJECT_ROOT="$arg"; fi
+      ;;
+  esac
+done
+
+# Auto-detect project root
+if [ -z "$PROJECT_ROOT" ]; then
+  dir="$(pwd)"
+  while [ "$dir" != "/" ]; do
+    if [ -d "$dir/.harness" ]; then PROJECT_ROOT="$dir"; break; fi
+    dir="$(dirname "$dir")"
+  done
+fi
+
+if [ -z "$PROJECT_ROOT" ] || [ ! -d "$PROJECT_ROOT/.harness" ]; then
+  echo "Error: .harness/ directory not found."
+  echo "Usage: bash scripts/harness-tmux.sh [project-root]"
+  exit 1
+fi
+
+echo "Project: $PROJECT_ROOT"
+echo "Session: $SESSION_NAME"
+
+# Kill existing session if any
+tmux kill-session -t "$SESSION_NAME" 2>/dev/null || true
+
+# ── Create tmux session ──
+# Pane 0 (left, Main): interactive shell at project root
+tmux new-session -d -s "$SESSION_NAME" -c "$PROJECT_ROOT" -x 200 -y 50
+
+# Split right column (40% width)
+tmux split-window -h -l 80 -t "$SESSION_NAME" -c "$PROJECT_ROOT"
+
+# Pane 1 (top-right): Dashboard
+tmux send-keys -t "${SESSION_NAME}.1" "bash ${SCRIPT_DIR}/harness-dashboard.sh '${PROJECT_ROOT}'" Enter
+
+# Split pane 1 vertically for Monitor
+tmux split-window -v -t "${SESSION_NAME}.1" -c "$PROJECT_ROOT"
+
+# Pane 2 (mid-right): Monitor
+tmux send-keys -t "${SESSION_NAME}.2" "bash ${SCRIPT_DIR}/harness-monitor.sh '${PROJECT_ROOT}'" Enter
+
+# Split pane 2 vertically for Eval
+tmux split-window -v -t "${SESSION_NAME}.2" -c "$PROJECT_ROOT"
+
+# Pane 3 (bottom-right): Eval Watcher
+tmux send-keys -t "${SESSION_NAME}.3" "bash ${SCRIPT_DIR}/harness-eval-watcher.sh '${PROJECT_ROOT}' ${USE_AI}" Enter
+
+# ── Layout adjustments ──
+# Select left pane (Main) — this is where the user works
+tmux select-pane -t "${SESSION_NAME}.0"
+
+# Set pane titles (requires tmux >= 3.2 with pane-border-format)
+tmux select-pane -t "${SESSION_NAME}.0" -T "Main"
+tmux select-pane -t "${SESSION_NAME}.1" -T "Dashboard"
+tmux select-pane -t "${SESSION_NAME}.2" -T "Monitor"
+tmux select-pane -t "${SESSION_NAME}.3" -T "Eval Review"
+
+# Enable pane border titles
+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
+
+# ── Attach or print info ──
+if [ "$DETACH" = true ]; then
+  echo ""
+  echo "Session created. Attach with:"
+  echo "  tmux attach -t $SESSION_NAME"
+else
+  # If already in tmux, switch; otherwise attach
+  if [ -n "${TMUX:-}" ]; then
+    tmux switch-client -t "$SESSION_NAME"
+  else
+    echo ""
+    echo "Launching harness-studio..."
+    echo "  Main (left)        : Interactive terminal — run 'claude' here"
+    echo "  Dashboard (right↑) : Real-time progress"
+    echo "  Monitor (right↔)   : Agent lifecycle events"
+    echo "  Eval (right↓)      : Evaluation summaries"
+    echo ""
+    tmux attach -t "$SESSION_NAME"
+  fi
+fi

package/scripts/lib/harness-audit.sh

@@ -0,0 +1,113 @@
+#!/bin/bash
+# harness-audit.sh — Audit log 헬퍼
+#
+# 라이프사이클: Planner 시작 → Eval 통과 (1 sprint cycle)
+# 새 Planner/Dispatcher 사이클 시작 시 이전 로그는 archive로 이동.
+#
+# 사용법:
+#   source scripts/lib/harness-audit.sh
+#   audit_log "gen-backend" "develop" "start" "apps/service-user/" "User 서비스 CRUD 구현"
+#   audit_log "eval-func"   "review"  "complete" "POST /api/auth" "FAIL: 409→400 contract 불일치"
+#   audit_log "gen-backend" "handoff" "start" "→eval-functional" ""
+
+AUDIT_LOG_FILE=""
+
+# ─────────────────────────────────────────
+# init_audit — audit.log 경로 설정 + 헤더 생성
+# Args: $1 = project root
+# ─────────────────────────────────────────
+init_audit() {
+  local project_root="${1:-.}"
+  AUDIT_LOG_FILE="$project_root/.harness/actions/audit.log"
+
+  # 디렉토리 보장
+  mkdir -p "$(dirname "$AUDIT_LOG_FILE")"
+}
+
+# ─────────────────────────────────────────
+# reset_audit — 새 사이클 시작 시 로그 초기화
+# 이전 로그가 있으면 archive로 이동
+# Args: $1 = project root, $2 = sprint number (optional)
+# ─────────────────────────────────────────
+reset_audit() {
+  local project_root="${1:-.}"
+  local sprint_num="${2:-0}"
+  init_audit "$project_root"
+
+  # 기존 로그가 있으면 archive로 이동
+  if [ -f "$AUDIT_LOG_FILE" ] && [ -s "$AUDIT_LOG_FILE" ]; then
+    local archive_dir="$project_root/.harness/archive"
+    mkdir -p "$archive_dir"
+    local ts
+    ts=$(date +%Y%m%d_%H%M%S)
+    mv "$AUDIT_LOG_FILE" "$archive_dir/audit_s${sprint_num}_${ts}.log"
+  fi
+
+  # 새 로그 헤더
+  cat > "$AUDIT_LOG_FILE" <<HEADER
+# Harness Audit Log
+# Cycle started: $(date -u +%Y-%m-%dT%H:%M:%SZ)
+# Format: TIMESTAMP | AGENT | ACTION | STATUS | TARGET | DETAIL
+#─────────────────────────────────────────────────────────────────────────
+HEADER
+}
+
+# ─────────────────────────────────────────
+# audit_log — 로그 엔트리 추가
+#
+# Args:
+#   $1 = agent     (planner, gen-backend, gen-frontend, eval-func, eval-visual)
+#   $2 = action    (develop, review, handoff, plan, gate)
+#   $3 = status    (start, complete, fail, skip)
+#   $4 = target    (파일 경로, 엔드포인트, 에이전트명 등)
+#   $5 = detail    (설명, 결과 등)
+# ─────────────────────────────────────────
+audit_log() {
+  if [ -z "$AUDIT_LOG_FILE" ] || [ ! -f "$AUDIT_LOG_FILE" ]; then
+    return 0  # audit 미초기화 시 silent pass
+  fi
+
+  local agent="${1:-unknown}"
+  local action="${2:-unknown}"
+  local log_status="${3:-unknown}"
+  local target="${4:-}"
+  local detail="${5:-}"
+  local ts
+  ts=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+  # 고정폭 포맷
+  printf "%-20s | %-14s | %-8s | %-8s | %-30s | %s\n" \
+    "$ts" "$agent" "$action" "$log_status" "$target" "$detail" >> "$AUDIT_LOG_FILE"
+}
+
+# ─────────────────────────────────────────
+# audit_handoff — 핸즈오프 기록 (편의 함수)
+# Args: $1=from_agent, $2=to_agent, $3=status(start|complete)
+# ─────────────────────────────────────────
+audit_handoff() {
+  audit_log "$1" "handoff" "$3" "→${2}" ""
+}
+
+# ─────────────────────────────────────────
+# audit_gate — 게이트 체크 기록 (편의 함수)
+# Args: $1=gate_name, $2=status(pass|fail), $3=detail
+# ─────────────────────────────────────────
+audit_gate() {
+  audit_log "system" "gate" "$2" "$1" "$3"
+}
+
+# ─────────────────────────────────────────
+# render_audit — audit.log를 읽기 좋게 출력
+# Args: $1 = project root (optional)
+# ─────────────────────────────────────────
+render_audit() {
+  local project_root="${1:-.}"
+  local log_file="$project_root/.harness/actions/audit.log"
+
+  if [ ! -f "$log_file" ]; then
+    echo "  (audit log not yet created)"
+    return 0
+  fi
+
+  cat "$log_file"
+}