@walwal-harness/cli 2.5.0 → 3.2.0

package/assets/templates/evaluation-visual.md.template

@@ -0,0 +1,151 @@
+# Evaluation — Visual (Sprint {{SPRINT}})
+
+> Generated by: evaluator-visual
+> Date: {{DATE}}
+> Verdict: **PENDING**
+
+## 1. Scoring Rubric
+
+> **Threshold: 2.80 / 3.00 = PASS**
+> Score 2.79 이하는 이유를 불문하고 FAIL.
+> 모든 항목에 Evidence(스크린샷 경로 또는 DOM 스냅샷)를 반드시 기입. Evidence 없는 Score는 0점 처리.
+
+| # | Criterion | Weight | Score (0-3) | Evidence |
+|---|-----------|--------|-------------|----------|
+| V1 | 레이아웃 정확성 — 모든 페이지가 디자인 의도대로 배치, 겹침/넘침/잘림 없음 | 20% | | |
+| V2 | 반응형 적합성 — 최소 3개 뷰포트(mobile 375px, tablet 768px, desktop 1280px)에서 정상 렌더링 | 20% | | |
+| V3 | 접근성 (a11y) — WCAG 2.1 AA 준수, axe-core 위반 0건, 키보드 네비게이션 가능, ARIA 라벨 존재 | 20% | | |
+| V4 | 시각적 일관성 — 색상/타이포/간격이 디자인 시스템과 일치, AI슬롭 패턴(그라데이션 남용, 무의미한 아이콘, 과도한 그림자) 없음 | 20% | | |
+| V5 | 인터랙션 피드백 — 로딩 상태, 에러 상태, 빈 상태, 호버/포커스 상태 모두 구현됨 | 20% | | |
+
+### Scoring Guide (엄격 적용)
+
+| Score | 의미 | 기준 |
+|-------|------|------|
+| 3 | 완벽 | 모든 뷰포트, 모든 상태에서 결함 없음. 프로덕션 출시 가능 수준 |
+| 2 | 충족 | 핵심 화면 정상이나 경미한 시각 이슈 1-2건 (1px 오차, 미사용 상태 아이콘 누락 등) |
+| 1 | 부분 충족 | 특정 뷰포트에서 레이아웃 깨짐, 또는 접근성 위반 3건 이상 |
+| 0 | 미충족 | 렌더링 실패, 빈 화면, 또는 핵심 UI 요소 누락 |
+
+### Anti-Rubber-Stamping Check
+
+Score를 기입하기 전에 반드시 아래 질문에 답하라:
+- [ ] "이 페이지를 실제로 3개 뷰포트에서 스크린샷을 찍어 확인했는가?" (추측 = 0점)
+- [ ] "axe-core 또는 접근성 검사를 실제로 실행했는가?" (미실행 = V3 최대 1점)
+- [ ] "이전 Sprint 스크린샷과 비교하여 의도치 않은 시각 변경이 없는지 확인했는가?"
+- [ ] "내가 이 UI를 직접 만들었다면, 이 수준으로 디자인 리뷰를 통과시키겠는가?" (NO = FAIL)
+
+## 2. Screenshot Matrix
+
+> 모든 페이지 x 3개 뷰포트의 스크린샷. 누락 셀이 있으면 해당 페이지 Score 산정 불가.
+
+| Page | Mobile (375px) | Tablet (768px) | Desktop (1280px) | Issues |
+|------|---------------|----------------|-------------------|--------|
+| | | | | |
+
+**Screenshot Coverage**: 0/0 pages x 3 viewports = 0/0
+
+## 3. Accessibility Audit
+
+> axe-core 또는 Playwright accessibility snapshot 결과.
+
+| Page | Violations | Critical | Serious | Moderate | Minor |
+|------|-----------|----------|---------|----------|-------|
+| | | | | | |
+
+**a11y Summary**: 0 total violations across 0 pages
+**Critical 또는 Serious 위반이 1건이라도 있으면 V3 = 0**
+
+## 4. Interaction States Checklist
+
+> 각 핵심 컴포넌트의 상태별 구현 확인.
+
+| Component | Default | Loading | Error | Empty | Hover | Focus | Disabled |
+|-----------|---------|---------|-------|-------|-------|-------|----------|
+| | | | | | | | |
+
+**상태 커버리지**: 0/0 components x states
+
+## 5. AI Slop Detection
+
+> AI 생성 UI의 흔한 저품질 패턴 감지.
+
+| Pattern | Detected? | Location | Severity |
+|---------|-----------|----------|----------|
+| 무의미한 그라데이션 | | | |
+| 과도한 그림자/블러 | | | |
+| 장식용 아이콘 남발 | | | |
+| 불필요한 애니메이션 | | | |
+| 일관성 없는 간격/정렬 | | | |
+| placeholder 텍스트 미교체 | | | |
+| 깨진 이미지/아이콘 | | | |
+
+**AI Slop이 2건 이상 감지되면 V4 = 최대 1점**
+
+## 6. Regression Visual Diff
+
+> 이전 Sprint 스크린샷과 현재 비교. 의도치 않은 시각 변경 감지.
+> Sprint 1이면 "N/A - 첫 스프린트"로 기입.
+
+| Page | Viewport | Change Detected | Intentional? | Notes |
+|------|----------|----------------|-------------|-------|
+| | | | | |
+
+**의도치 않은 시각 변경이 1건이라도 있으면 Verdict = FAIL**
+
+## 7. Cross-Validation with Functional
+
+> evaluation-functional.md의 Cross-Validation Data와 교차 검증.
+
+| Check | Functional Result | Visual Result | Consistent? |
+|-------|------------------|---------------|-------------|
+| 페이지 존재 여부 | endpoints_tested → pages | 실제 렌더링 확인 | |
+| 폼 제출 결과 | API 응답 status | UI 피드백 메시지 | |
+| 에러 표시 | 에러 응답 코드 | 에러 UI 렌더링 | |
+
+**불일치가 1건이라도 있으면 관련 Feature의 해당 항목 재검증 필요 → CONDITIONAL FAIL**
+
+```json
+{
+  "evaluator": "visual",
+  "sprint": {{SPRINT}},
+  "verdict": "PENDING",
+  "total_score": 0.00,
+  "threshold": 2.80,
+  "criteria_scores": {
+    "V1_layout": 0,
+    "V2_responsive": 0,
+    "V3_accessibility": 0,
+    "V4_consistency": 0,
+    "V5_interaction_states": 0
+  },
+  "screenshot_coverage": 0.0,
+  "a11y_violations": { "critical": 0, "serious": 0, "moderate": 0, "minor": 0 },
+  "ai_slop_count": 0,
+  "regression_visual_changes": 0,
+  "cross_validation_inconsistencies": 0,
+  "pages_tested": []
+}
+```
+
+## 8. Final Verdict
+
+| Metric | Value |
+|--------|-------|
+| Weighted Score | 0.00 / 3.00 |
+| Threshold | 2.80 |
+| Screenshot Coverage | 0% |
+| a11y Critical+Serious | 0 |
+| AI Slop Count | 0 |
+| Regression Visual Changes | 0 |
+| Cross-Validation Inconsistencies | 0 |
+| **Verdict** | **PENDING** |
+
+### Verdict Rules (위반 불가)
+1. Weighted Score < 2.80 → **FAIL**
+2. Screenshot 누락 페이지 존재 → 해당 페이지 관련 항목 Score = 0으로 재계산
+3. a11y Critical 또는 Serious > 0 → V3 = 0으로 재계산
+4. AI Slop >= 2 → V4 = 최대 1점으로 재계산
+5. Regression 의도치 않은 변경 > 0 → **FAIL** (점수 무관)
+6. Cross-Validation 불일치 > 0 → **CONDITIONAL FAIL** (해당 Feature 재검증)
+7. Evidence 누락 항목 존재 → 해당 항목 Score = 0으로 재계산

package/assets/templates/memory.md

@@ -3,4 +3,24 @@
 > Dispatcher가 관리. **모든 에이전트**는 세션 시작 시 이 파일을 읽고 학습된 규칙을 따릅니다.
 > gotchas(에이전트별 실수 기록)와 달리, 이 파일은 **프로젝트 전체에 적용되는 구조적 교훈**을 담습니다.
 
+## 항목 형식
+
+```markdown
+### [M-NNN] 간결한 제목
+- **Date**: YYYY-MM-DD
+- **Status**: unverified | verified
+- **TTL**: YYYY-MM-DD (기본 +60일. 만료 후 Planner가 리뷰)
+- **Lesson**: 교훈 내용
+- **Context**: 발견 배경
+- **Applies to**: 적용 대상 에이전트/상황
+```
+
+## 오염 방어 규칙
+
+- 새 항목은 반드시 `unverified` 상태로 시작
+- Planner가 스프린트 리뷰 시 유효성 확인 후 `verified` 승격
+- TTL 만료 항목은 Planner가 리뷰: 갱신 또는 삭제
+- 환각(hallucination) 의심 항목: 코드/git 이력으로 검증 불가하면 즉시 삭제
+- 항목이 15개 초과 시 가장 오래된 unverified 항목부터 정리
+
 <!-- 항목이 추가되면 아래에 기록됩니다 -->

package/assets/templates/progress.json.template

@@ -17,6 +17,12 @@
     "message": null,
     "retry_target": null
   },
+  "artifacts": {
+    "plan.md": { "status": "pending", "updated_by": null, "updated_at": null },
+    "feature-list.json": { "status": "pending", "updated_by": null, "updated_at": null },
+    "api-contract.json": { "status": "pending", "updated_by": null, "updated_at": null },
+    "sprint-contract.md": { "status": "pending", "updated_by": null, "updated_at": null }
+  },
   "updated_at": "{{DATE}}",
   "history": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@walwal-harness/cli",
-  "version": "2.5.0",
+  "version": "3.2.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"
@@ -34,5 +34,8 @@
     "scripts/",
     "assets/",
     "gotchas/"
-  ]
+  ],
+  "dependencies": {
+    "@walwal-harness/cli": "^3.2.0"
+  }
 }

package/scripts/harness-next.sh

@@ -6,6 +6,7 @@ set -e
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 source "$SCRIPT_DIR/lib/harness-render-progress.sh"
+source "$SCRIPT_DIR/lib/harness-guardrail.sh"
 
 # ─────────────────────────────────────────
 # Resolve project root
@@ -71,6 +72,90 @@ substitute_fe_stack() {
   echo "$sub"
 }
 
+# ─────────────────────────────────────────
+# Pre-Eval Gate — deterministic checks before Evaluator
+#   Generator가 완료되고 다음이 Evaluator일 때, lint/type/test를 먼저 실행.
+#   실패 시 Evaluator를 건너뛰고 Generator로 리라우팅.
+# ─────────────────────────────────────────
+run_pre_eval_gate() {
+  local next="$1"
+  local gate_enabled
+  gate_enabled=$(jq -r '.flow.pre_eval_gate.enabled // false' "$CONFIG" 2>/dev/null)
+  if [ "$gate_enabled" != "true" ]; then return 0; fi
+
+  # Evaluator 에이전트인지 확인
+  case "$next" in
+    evaluator-*) ;;
+    *) return 0 ;;
+  esac
+
+  local timeout
+  timeout=$(jq -r '.flow.pre_eval_gate.timeout_seconds // 120' "$CONFIG" 2>/dev/null)
+
+  # 실패 위치 결정 (backend or frontend)
+  local location="backend"
+  local checks_key="backend_checks"
+  if [ "$current_agent" = "generator-frontend" ] || [ "$current_agent" = "generator-frontend-flutter" ]; then
+    location="frontend"
+    checks_key="frontend_checks"
+  fi
+
+  local -a checks
+  mapfile -t checks < <(jq -r ".flow.pre_eval_gate.${checks_key}[]" "$CONFIG" 2>/dev/null)
+
+  if [ ${#checks[@]} -eq 0 ]; then return 0; fi
+
+  echo ""
+  echo "  ── Pre-Eval Gate ──────────────────────"
+  local all_pass=true
+  local fail_log=""
+
+  for cmd in "${checks[@]}"; do
+    printf "  %-40s " "$cmd"
+    local output
+    if output=$(cd "$PROJECT_ROOT" && timeout "${timeout}s" bash -c "$cmd" 2>&1); then
+      echo "✓"
+    else
+      echo "✗"
+      all_pass=false
+      fail_log+="[FAIL] $cmd"$'\n'"$output"$'\n\n'
+    fi
+  done
+
+  if [ "$all_pass" = true ]; then
+    echo "  Gate: PASS — proceeding to $next"
+    echo ""
+    return 0
+  else
+    echo ""
+    echo "  Gate: FAIL — rerouting to $current_agent"
+    echo ""
+
+    # progress.json 업데이트: 실패 기록 + Generator로 리라우팅
+    local new_retry=$((retry_count + 1))
+    local fail_summary
+    fail_summary=$(echo "$fail_log" | head -20)
+
+    jq --arg agent "$current_agent" \
+       --arg loc "$location" \
+       --arg msg "Pre-eval gate failed: $fail_summary" \
+       --arg target "$current_agent" \
+       --argjson retry "$new_retry" \
+       '.sprint.status = "failed" |
+        .sprint.retry_count = $retry |
+        .agent_status = "failed" |
+        .next_agent = $target |
+        .failure.agent = $agent |
+        .failure.location = $loc |
+        .failure.message = $msg |
+        .failure.retry_target = $target' "$PROGRESS" > "${PROGRESS}.tmp" && mv "${PROGRESS}.tmp" "$PROGRESS"
+
+    # next_agent를 Generator로 덮어쓰기
+    next_agent="$current_agent"
+    return 1
+  fi
+}
+
 # ─────────────────────────────────────────
 # Determine next agent
 # ─────────────────────────────────────────
@@ -138,6 +223,71 @@ if [ "$agent_status" = "completed" ] && [ "$next_agent" = "null" ]; then
   next_agent=$(compute_next_agent "$current_agent" "$agent_status")
 fi
 
+# ─────────────────────────────────────────
+# Artifact Prerequisites — 선행 아티팩트 상태 검증
+# ─────────────────────────────────────────
+verify_artifact_prerequisites() {
+  local target_agent="$1"
+  local states_order='["pending","draft","reviewed","approved"]'
+
+  # 에이전트의 prerequisites 가져오기
+  local prereqs
+  prereqs=$(jq -r ".artifacts.prerequisites[\"${target_agent}\"] // empty" "$CONFIG" 2>/dev/null)
+  if [ -z "$prereqs" ] || [ "$prereqs" = "null" ]; then return 0; fi
+
+  local all_met=true
+  echo ""
+  echo "  ── Artifact Prerequisites ─────────────"
+
+  # prereqs의 각 키(artifact명)를 순회
+  while IFS='=' read -r artifact required_status; do
+    artifact=$(echo "$artifact" | tr -d '"' | tr -d ' ')
+    required_status=$(echo "$required_status" | tr -d '"' | tr -d ' ')
+    if [ -z "$artifact" ]; then continue; fi
+
+    local current_status
+    current_status=$(jq -r ".artifacts[\"${artifact}\"].status // \"pending\"" "$PROGRESS" 2>/dev/null)
+
+    # 상태 순서 비교
+    local required_idx current_idx
+    required_idx=$(echo "$states_order" | jq "index(\"$required_status\") // 0")
+    current_idx=$(echo "$states_order" | jq "index(\"$current_status\") // 0")
+
+    if [ "$current_idx" -ge "$required_idx" ]; then
+      printf "  ✓ %-25s %s (required: %s)\n" "$artifact" "$current_status" "$required_status"
+    else
+      printf "  ✗ %-25s %s (required: %s)\n" "$artifact" "$current_status" "$required_status"
+      all_met=false
+    fi
+  done < <(jq -r ".artifacts.prerequisites[\"${target_agent}\"] | to_entries[] | \"\(.key)=\(.value)\"" "$CONFIG" 2>/dev/null)
+
+  echo ""
+
+  if [ "$all_met" = true ]; then
+    echo "  Prerequisites: PASS"
+  else
+    echo "  Prerequisites: FAIL — preceding agent must complete artifacts first"
+  fi
+  echo ""
+
+  [ "$all_met" = true ] && return 0 || return 1
+}
+
+# ─────────────────────────────────────────
+# Runtime Guardrail — 파일 소유권 검증
+# ─────────────────────────────────────────
+if [ "$agent_status" = "completed" ]; then
+  verify_file_ownership "$PROJECT_ROOT" || true
+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
+fi
+
 # ─────────────────────────────────────────
 # Render progress
 # ─────────────────────────────────────────
@@ -149,6 +299,18 @@ echo ""
 # Generate next-prompt.txt
 # ─────────────────────────────────────────
 if [ "$next_agent" != "null" ] && [ "$next_agent" != "archive" ] && [ "$agent_status" != "blocked" ]; then
+  # ── Escalation check: 3회 실패 시 Planner에게 scope 축소 요청 ──
+  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 축소/접근 변경 요청"
+    next_agent="planner"
+    # progress.json에 에스컬레이션 기록
+    jq --arg msg "Escalated after ${retry_count} failures. Planner must review scope or approach." \
+       '.next_agent = "planner" |
+        .failure.message = $msg |
+        .failure.retry_target = "planner"' "$PROGRESS" > "${PROGRESS}.tmp" && mv "${PROGRESS}.tmp" "$PROGRESS"
+  fi
+
   # Build prompt
   prompt="/harness-${next_agent} 를 실행하세요."
 
@@ -162,14 +324,105 @@ if [ "$next_agent" != "null" ] && [ "$next_agent" != "archive" ] && [ "$agent_st
 
   prompt+=$'\n'".harness/progress.json을 읽고 현재 상태를 확인하세요."
 
-  # Add failure context if retrying
+  # Add failure context if retrying (include previous failure summary)
   failure_msg=$(jq -r '.failure.message // empty' "$PROGRESS")
   if [ -n "$failure_msg" ] && [ "$failure_msg" != "null" ]; then
     prompt+=$'\n\n'"이전 실패 사유: ${failure_msg}"
+    prompt+=$'\n'"같은 접근을 반복하지 말고, 실패 원인을 분석한 후 다른 전략으로 시도하세요."
   fi
 
   echo "$prompt" > "$NEXT_PROMPT"
 
+  # ── Generate structured handoff.json ──
+  HANDOFF="$PROJECT_ROOT/.harness/handoff.json"
+  FEATURE_LIST="$PROJECT_ROOT/.harness/actions/feature-list.json"
+
+  # Collect available artifacts
+  local -a artifacts_ready=()
+  for f in plan.md feature-list.json api-contract.json sprint-contract.md evaluation-functional.md evaluation-visual.md; do
+    if [ -f "$PROJECT_ROOT/.harness/actions/$f" ]; then
+      artifacts_ready+=("$f")
+    fi
+  done
+  local artifacts_json
+  artifacts_json=$(printf '%s\n' "${artifacts_ready[@]}" | jq -R . | jq -s .)
+
+  # Collect focus features (incomplete ones)
+  local focus_features="[]"
+  if [ -f "$FEATURE_LIST" ]; then
+    focus_features=$(jq '[.features[]? | select(.passes == null or (.passes | length) == 0 or ((.passes // []) | map(select(. == "evaluator-functional")) | length == 0)) | .id] | .[0:5]' "$FEATURE_LIST" 2>/dev/null || echo "[]")
+  fi
+
+  # ── Regression data: collect previous sprint's passed AC from archive ──
+  local regression_source="null"
+  local prev_sprint=$((sprint_num - 1))
+  local prev_archive="$PROJECT_ROOT/.harness/archive/sprint-$(printf '%03d' $prev_sprint)"
+  if [ "$prev_sprint" -ge 1 ] && [ -d "$prev_archive" ]; then
+    if [ -f "$prev_archive/feature-list.json" ]; then
+      regression_source=$(jq '{
+        sprint: '"$prev_sprint"',
+        passed_features: [.features[]? | select((.passes // []) | map(select(. == "evaluator-functional")) | length > 0) | {id, name, acceptance_criteria}],
+        archive_path: "'"$prev_archive"'"
+      }' "$prev_archive/feature-list.json" 2>/dev/null || echo "null")
+    fi
+  fi
+
+  # ── Eval-specific scoring config ──
+  local eval_config="null"
+  local cross_validation_data="null"
+  case "$next_agent" in
+    evaluator-*)
+      eval_config=$(jq '{
+        pass_threshold: .evaluation.scoring.pass_threshold,
+        scale: .evaluation.scoring.scale,
+        verdict_rules: .evaluation.scoring.verdict_rules,
+        regression_enabled: .evaluation.regression.enabled,
+        cross_validation_enabled: .evaluation.cross_validation.enabled,
+        adversarial_rules: .agents["'"$next_agent"'"].adversarial_rules.rules,
+        forbidden: .agents["'"$next_agent"'"].adversarial_rules.forbidden
+      }' "$CONFIG" 2>/dev/null || echo "null")
+      ;;
+  esac
+
+  # ── Cross-Validation: evaluator-visual이면 functional 결과 파싱 ──
+  if [ "$next_agent" = "evaluator-visual" ]; then
+    local func_eval="$PROJECT_ROOT/.harness/actions/evaluation-functional.md"
+    if [ -f "$func_eval" ]; then
+      # evaluation-functional.md 내 JSON 코드블록에서 Cross-Validation Data 추출
+      cross_validation_data=$(sed -n '/```json/,/```/p' "$func_eval" | tail -n +2 | head -n -1 | jq 'select(.evaluator == "functional")' 2>/dev/null || echo "null")
+    fi
+  fi
+
+  # Build handoff.json
+  jq -n \
+    --arg from "${current_agent:-dispatcher}" \
+    --arg to "$next_agent" \
+    --argjson sprint "$sprint_num" \
+    --argjson retry "$retry_count" \
+    --arg status "$sprint_status" \
+    --arg failure_msg "${failure_msg:-}" \
+    --argjson artifacts "$artifacts_json" \
+    --argjson focus "$focus_features" \
+    --argjson regression "$regression_source" \
+    --argjson eval_config "$eval_config" \
+    --argjson cross_val "$cross_validation_data" \
+    --arg timestamp "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+    '{
+      from: $from,
+      to: $to,
+      sprint: $sprint,
+      retry_count: $retry,
+      sprint_status: $status,
+      failure_context: (if $failure_msg != "" then $failure_msg else null end),
+      artifacts_ready: $artifacts,
+      focus_features: $focus,
+      regression: $regression,
+      eval_config: $eval_config,
+      cross_validation_from_functional: $cross_val,
+      warnings: [],
+      timestamp: $timestamp
+    }' > "$HANDOFF"
+
 elif [ "$next_agent" = "archive" ]; then
   cat > "$NEXT_PROMPT" <<'PROMPT'
 Sprint 문서를 아카이브 하세요.

package/scripts/harness-session-start.sh

@@ -1,31 +1,34 @@
 #!/bin/bash
-# harness-session-start.sh — SessionStart 훅
-# Claude Code 세션 시작 시 자동 실행되어 현재 하네스 상태를 출력한다.
-# .claude/settings.json의 SessionStart 훅으로 등록된다.
+# harness-session-start.sh — SessionStart 훅 (compact)
+# statusline이 상시 상태를 표시하므로, 여기서는 핵심 안내만 출력.
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 LIB="$SCRIPT_DIR/lib/harness-render-progress.sh"
 
-# lib이 없으면 silent exit (훅이므로 에러 출력하지 않음)
 if [ ! -f "$LIB" ]; then exit 0; fi
 source "$LIB"
-
-# jq 없으면 silent exit
 command -v jq &>/dev/null || exit 0
 
-# .harness/ 찾기
 PROJECT_ROOT="$(resolve_harness_root "." 2>/dev/null)" || exit 0
-
 PROGRESS="$PROJECT_ROOT/.harness/progress.json"
 [ -f "$PROGRESS" ] || exit 0
 
-# init 상태면 간단 안내만
 sprint_status=$(jq -r '.sprint.status // "init"' "$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)
+
+# init 상태: 간단 안내
 if [ "$sprint_status" = "init" ]; then
   echo "# Harness ready — say \"하네스 엔지니어링 시작\" or /harness-dispatcher"
   exit 0
 fi
 
-# Feature-level 프로그래스 출력
-render_progress "$PROJECT_ROOT"
-render_agent_bar "$PROJECT_ROOT"
+# 활성 세션: 다음 액션만 안내 (상세 프로그래스는 statusline에서 상시 표시)
+if [ "$agent_status" = "blocked" ]; then
+  echo "# Harness BLOCKED — user intervention required. Run: bash scripts/harness-next.sh"
+elif [ "$next_agent" != "none" ] && [ "$next_agent" != "null" ]; then
+  echo "# Harness: next → /harness-${next_agent}"
+elif [ "$current_agent" != "none" ] && [ "$current_agent" != "null" ]; then
+  echo "# Harness: ${current_agent} [${agent_status}]"
+fi

package/scripts/harness-statusline.sh

@@ -0,0 +1,93 @@
+#!/bin/bash
+# harness-statusline.sh — Claude Code statusline hook
+# 터미널 하단에 항상 고정되는 1줄 compact 상태 표시.
+# stdin: Claude Code JSON payload (model, context_window, cost 등)
+# stdout: 상태 문자열 (Claude Code가 터미널 하단에 렌더링)
+
+# Read Claude Code session data from stdin
+input=$(cat)
+
+# Extract Claude Code built-in data
+context_pct=$(echo "$input" | jq -r '.context_window.used_percentage // 0' 2>/dev/null | cut -d. -f1)
+cost=$(echo "$input" | jq -r '.cost.total_cost_usd // 0' 2>/dev/null)
+
+# Resolve project root (walk up from cwd)
+CWD=$(echo "$input" | jq -r '.workspace.current_dir // empty' 2>/dev/null)
+if [ -z "$CWD" ]; then CWD="$PWD"; fi
+
+PROJECT_ROOT="$CWD"
+while [ "$PROJECT_ROOT" != "/" ]; do
+  if [ -d "$PROJECT_ROOT/.harness" ]; then break; fi
+  PROJECT_ROOT="$(dirname "$PROJECT_ROOT")"
+done
+
+PROGRESS="$PROJECT_ROOT/.harness/progress.json"
+FEATURE_LIST="$PROJECT_ROOT/.harness/actions/feature-list.json"
+PIPELINE_JSON="$PROJECT_ROOT/.harness/actions/pipeline.json"
+
+# No harness → minimal status
+if [ ! -f "$PROGRESS" ]; then
+  echo "harness: not initialized | ctx ${context_pct}%"
+  exit 0
+fi
+
+# Read harness state
+sprint_num=$(jq -r '.sprint.number // 0' "$PROGRESS" 2>/dev/null)
+sprint_status=$(jq -r '.sprint.status // "init"' "$PROGRESS" 2>/dev/null)
+pipeline=$(jq -r '.pipeline // "?"' "$PROGRESS" 2>/dev/null)
+current_agent=$(jq -r '.current_agent // "none"' "$PROGRESS" 2>/dev/null)
+agent_status=$(jq -r '.agent_status // "pending"' "$PROGRESS" 2>/dev/null)
+next_agent=$(jq -r '.next_agent // "none"' "$PROGRESS" 2>/dev/null)
+retry_count=$(jq -r '.sprint.retry_count // 0' "$PROGRESS" 2>/dev/null)
+
+# Pipeline short name
+case "$pipeline" in
+  FULLSTACK) pl="FULL" ;;
+  FE-ONLY)   pl="FE" ;;
+  BE-ONLY)   pl="BE" ;;
+  null|"?")  pl="?" ;;
+  *)         pl="$pipeline" ;;
+esac
+
+# Agent short name (strip harness prefix)
+agent_short="${current_agent#generator-}"
+agent_short="${agent_short#evaluator-}"
+if [ "$current_agent" = "none" ] || [ "$current_agent" = "null" ]; then
+  agent_short="$next_agent"
+  if [ "$agent_short" = "none" ] || [ "$agent_short" = "null" ]; then
+    agent_short="idle"
+  fi
+fi
+
+# Feature progress
+total_features=0
+completed_features=0
+if [ -f "$FEATURE_LIST" ]; then
+  total_features=$(jq '.features | length' "$FEATURE_LIST" 2>/dev/null || echo 0)
+  completed_features=$(jq '[.features[]? | select(
+    (.passes // []) | (
+      (map(select(. == "evaluator-functional")) | length > 0) and
+      (map(select(. == "evaluator-visual")) | length > 0)
+    )
+  )] | length' "$FEATURE_LIST" 2>/dev/null || echo 0)
+fi
+
+# Status indicator
+status_icon=""
+case "$agent_status" in
+  running)   status_icon=">" ;;
+  completed) status_icon="v" ;;
+  failed)    status_icon="x" ;;
+  blocked)   status_icon="!" ;;
+  *)         status_icon="-" ;;
+esac
+
+# Retry indicator
+retry_str=""
+if [ "$retry_count" -gt 0 ]; then
+  retry_str=" R${retry_count}"
+fi
+
+# Build compact status line
+# Format: [S1] FULL | >backend | 2/5 feat | R0 | ctx 45% | $1.23
+echo "[S${sprint_num}] ${pl} | ${status_icon}${agent_short}${retry_str} | ${completed_features}/${total_features} feat | ctx ${context_pct}% | \$${cost}"