@walwal-harness/cli 5.6.5 → 5.7.1

package/assets/templates/progress.json.template

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

package/bin/init.js

@@ -346,6 +346,14 @@ function scaffoldHarness() {
         fs.writeFileSync(progressPath, JSON.stringify(progress, null, 2) + '\n');
         log('progress.json migrated to v2 (mode + team_state added)');
       }
+      if (progress.version < 3) {
+        progress.version = 3;
+        if (!progress.dispatch) {
+          progress.dispatch = { counter: 0, id: null };
+        }
+        fs.writeFileSync(progressPath, JSON.stringify(progress, null, 2) + '\n');
+        log('progress.json migrated to v3 (dispatch counter added)');
+      }
     } catch (e) {
       log('WARNING: Could not migrate progress.json');
     }
@@ -1009,15 +1017,14 @@ function main() {
     log('║  Then say: "하네스 엔지니어링 시작"                        ║');
     log('║  Or invoke: /harness-dispatcher                          ║');
     log('║                                                          ║');
-    log('║  After Planner completes:                                ║');
-    log('║    /harness-team  → Team mode (auto parallel)            ║');
-    log('║    /harness-solo  → Solo mode (prompting sequential)     ║');
+    log('║  기본은 Solo 모드 (순차 진행) — 입력 불필요.              ║');
+    log('║  병렬 3팀 실행을 원하면 파이프라인 확정 후 /harness-team  ║');
     log('╚═══════════════════════════════════════════════════════════╝');
   } else {
     log('Next steps:');
     log('  1. Restart Claude Code session (/exit → re-enter directory)');
     log('  2. Say "하네스 엔지니어링 시작" or /harness-dispatcher');
-    log('  3. After Planner: /harness-team (team) or keep prompting (solo)');
+    log('  3. Solo 모드는 자동. Team 모드 원할 때만 파이프라인 확정 후 /harness-team');
   }
   console.log('');
 }

package/commands/harness-team.md

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

package/gotchas/README.md

@@ -19,19 +19,36 @@
 ## 항목 형식
 
 ```markdown
-### [G-NNN] 간결한 제목
+### [G-NNN] 간결한 제목  <!-- rule_id: <unique-key> -->
+- **Status**: unverified | verified | resolved
 - **Date**: YYYY-MM-DD
-- **Trigger**: 사용자가 한 말 (원문 요약)
+- **Source**: <작성 주체>        (예: "evaluator-functional:F-003" / "dispatcher:manual")
+- **Trigger**: 사용자가 한 말 또는 "Eval 자동 감지"
 - **Wrong**: 에이전트가 했던 잘못된 행동
 - **Right**: 올바른 행동
 - **Why**: 왜 잘못인지 근거
 - **Scope**: 이 규칙이 적용되는 조건/범위
+- **Occurrences**: 1
+- **Last-Seen**: YYYY-MM-DD
 ```
 
+## 작성 주체
+
+- **Dispatcher**: 사용자의 명시적 실수 지적을 Gotcha Flow 로 기록
+- **Evaluator (code-quality / functional / visual)**: evaluation-*.md 의 `gotcha_candidates` JSON 블록을 통해 자동 등록 (v5.7.1+). `harness-next.sh` 가 Evaluator 완료 직후 `scripts/harness-gotcha-register.sh --scan-evaluations` 로 처리.
+
+## Status 라이프사이클 (v5.7.1+)
+
+- **unverified**: 신규 자동/수동 등록 기본값. Generator 는 참조하지만 페널티 강도 낮음.
+- **verified**: Planner/사용자 리뷰 후 승격. 이후 위반 시 하드 페널티.
+- **resolved**: 근본 원인이 코드/스킬/컨벤션에 반영되어 더 이상 재발하지 않는 항목. 삭제 대신 태그 유지.
+
+Planner 는 스프린트 전환 시 `unverified` 항목을 검토해 `verified` 또는 제거 판정을 내린다 (AGENTS.md "메모리 오염 방어" 섹션).
+
 ## 관리 규칙
 
-- Dispatcher만 gotchas 파일에 쓰기 가능
+- Dispatcher + Evaluator 만 gotchas 파일에 쓰기 가능 (자동 등록 포함)
 - 각 에이전트는 자신의 gotchas 파일을 읽기 전용으로 참조
-- 중복 항목 금지 — 같은 실수는 기존 항목에 횟수 증가
-- 해결된 항목은 삭제하지 않고 `[RESOLVED]` 태그 추가
-- 항목이 20개 초과 시 가장 오래된 RESOLVED 항목부터 정리
+- 중복 항목 금지 — 동일 `rule_id` 는 `Occurrences` + `Last-Seen` 만 갱신
+- 해결된 항목: `Status: resolved` 또는 제목 뒤 `[RESOLVED]` 태그
+- 항목이 20개 초과 시 가장 오래된 resolved 항목부터 정리

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@walwal-harness/cli",
-  "version": "5.6.5",
+  "version": "5.7.1",
   "description": "Production harness for AI agent engineering — Solo/Team mode, Planner, Generator(BE/FE), Evaluator chain (Code-Quality → Functional → Visual), optional Brainstormer. Supports React, Next.js, and Flutter FE stacks.",
   "bin": {
     "walwal-harness": "bin/init.js"

package/scripts/harness-archive.sh

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

package/scripts/harness-dashboard.sh

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

package/scripts/harness-gotcha-memory.sh

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

package/scripts/harness-gotcha-register.sh

@@ -0,0 +1,259 @@
+#!/bin/bash
+# harness-gotcha-register.sh — Evaluator → Gotcha 자동 등록 파이프라인
+#
+# 사용법:
+#   1) 단일 항목 등록 (수동/스크립트):
+#      bash harness-gotcha-register.sh <project-root> \
+#        --target <agent> \
+#        --rule-id <rule-id> \
+#        --title "제목" \
+#        --wrong "잘못된 행동" \
+#        --right "올바른 행동" \
+#        --why "근거" \
+#        --scope "적용 범위" \
+#        --source "evaluator-functional:F-003"
+#
+#   2) 일괄 등록 (JSON stdin/파일):
+#      bash harness-gotcha-register.sh <project-root> --from-json <path>
+#      bash harness-gotcha-register.sh <project-root> --scan-evaluations
+#        └ .harness/actions/evaluation-*.md 의 ```gotcha_candidates``` 블록 전부 스캔
+#
+# 동작:
+#   - 대상 파일: .harness/gotchas/<target>.md (없으면 생성)
+#   - 중복 감지: 동일 rule_id 가 있으면 Occurrences +1, last_seen 갱신 (본문 수정 없음)
+#   - 신규: 다음 G-NNN 할당, Status: unverified 로 기록
+#   - 등록 성공 로그: .harness/progress.log 에 한 줄 append
+#
+# 등록 형식:
+#   ### [G-NNN] <title>  <!-- rule_id: <rule-id> -->
+#   - **Status**: unverified
+#   - **Date**: YYYY-MM-DD
+#   - **Source**: <source>   (예: "evaluator-functional:F-003")
+#   - **Trigger**: Eval 자동 감지
+#   - **Wrong**: <wrong>
+#   - **Right**: <right>
+#   - **Why**: <why>
+#   - **Scope**: <scope>
+#   - **Occurrences**: 1
+#   - **Last-Seen**: YYYY-MM-DD
+
+set -euo pipefail
+
+if [ $# -lt 1 ]; then
+  echo "usage: harness-gotcha-register.sh <project-root> [options]" >&2
+  exit 1
+fi
+
+PROJECT_ROOT="$1"
+shift
+PROJECT_ROOT="$(cd "$PROJECT_ROOT" && pwd)"
+
+command -v jq >/dev/null 2>&1 || { echo "[gotcha-register] ERROR: jq required" >&2; exit 1; }
+
+GOTCHAS_DIR="$PROJECT_ROOT/.harness/gotchas"
+ACTIONS_DIR="$PROJECT_ROOT/.harness/actions"
+mkdir -p "$GOTCHAS_DIR"
+
+TODAY="$(date +%Y-%m-%d)"
+
+# ─────────────────────────────────────────
+# 단일 항목을 .harness/gotchas/<target>.md 에 append
+#   $1: target agent (generator-backend, generator-frontend, evaluator-functional, ...)
+#   $2: rule_id (dedup key)
+#   $3: title
+#   $4: wrong
+#   $5: right
+#   $6: why
+#   $7: scope
+#   $8: source
+# ─────────────────────────────────────────
+register_one() {
+  local target="$1" rule_id="$2" title="$3" wrong="$4" right="$5" why="$6" scope="$7" source="$8"
+  local file="$GOTCHAS_DIR/${target}.md"
+
+  # Ensure file exists with header
+  if [ ! -f "$file" ]; then
+    cat > "$file" <<EOF
+# Gotchas — $target
+
+> Dispatcher + Evaluator 가 관리. $target 은 세션 시작 시 이 파일을 읽고 같은 실수를 반복하지 않습니다.
+> 신규 항목은 \`Status: unverified\` 로 기록되고, Planner 리뷰 후 \`verified\` 로 승격됩니다.
+
+EOF
+  fi
+
+  # Dedup by rule_id marker comment
+  if grep -qE "<!-- rule_id: ${rule_id} -->" "$file" 2>/dev/null; then
+    # Bump Occurrences + Last-Seen for matching block
+    awk -v rid="$rule_id" -v today="$TODAY" '
+      BEGIN { in_block = 0 }
+      /^### \[G-[0-9]+\].*<!-- rule_id: / {
+        in_block = (index($0, "rule_id: " rid " ") > 0 || index($0, "rule_id: " rid "\n") > 0 || $0 ~ ("rule_id: " rid " -->"))
+      }
+      in_block && /^- \*\*Occurrences\*\*:/ {
+        n = $NF + 0
+        print "- **Occurrences**: " (n + 1)
+        next
+      }
+      in_block && /^- \*\*Last-Seen\*\*:/ {
+        print "- **Last-Seen**: " today
+        next
+      }
+      /^### / && !/<!-- rule_id: / { in_block = 0 }
+      { print }
+    ' "$file" > "${file}.tmp" && mv "${file}.tmp" "$file"
+    echo "[gotcha-register] $target: dedup $rule_id (occurrence bumped)"
+    return 0
+  fi
+
+  # Allocate next G-NNN (|| true — pipefail-safe when no existing entries)
+  local next_num=""
+  next_num=$(grep -oE '^### \[G-[0-9]+\]' "$file" 2>/dev/null | grep -oE '[0-9]+' | sort -n | tail -1 || true)
+  next_num=$((${next_num:-0} + 1))
+  local g_id
+  g_id=$(printf 'G-%03d' "$next_num")
+
+  # Append new block
+  {
+    echo ""
+    echo "### [$g_id] $title  <!-- rule_id: $rule_id -->"
+    echo "- **Status**: unverified"
+    echo "- **Date**: $TODAY"
+    echo "- **Source**: $source"
+    echo "- **Trigger**: Eval 자동 감지"
+    echo "- **Wrong**: $wrong"
+    echo "- **Right**: $right"
+    echo "- **Why**: $why"
+    echo "- **Scope**: $scope"
+    echo "- **Occurrences**: 1"
+    echo "- **Last-Seen**: $TODAY"
+  } >> "$file"
+
+  echo "[gotcha-register] $target: registered $g_id ($rule_id) — unverified"
+
+  # Log to progress.log if present
+  local progress_log="$PROJECT_ROOT/.harness/progress.log"
+  if [ -f "$progress_log" ]; then
+    echo "$(date -u +%Y-%m-%dT%H:%M:%SZ) [gotcha] $target $g_id unverified — $title (source: $source)" >> "$progress_log"
+  fi
+}
+
+# ─────────────────────────────────────────
+# JSON 배열에서 일괄 등록
+#   schema: [{ target, rule_id, title, wrong, right, why, scope, source }]
+# ─────────────────────────────────────────
+register_from_json() {
+  local json="$1"
+  local count
+  count=$(echo "$json" | jq 'length' 2>/dev/null || echo 0)
+  if [ "$count" -eq 0 ]; then
+    return 0
+  fi
+
+  local i
+  for ((i=0; i<count; i++)); do
+    local t r ti w ri wh sc so
+    t=$(echo "$json"  | jq -r ".[$i].target // empty")
+    r=$(echo "$json"  | jq -r ".[$i].rule_id // empty")
+    ti=$(echo "$json" | jq -r ".[$i].title // empty")
+    w=$(echo "$json"  | jq -r ".[$i].wrong // empty")
+    ri=$(echo "$json" | jq -r ".[$i].right // empty")
+    wh=$(echo "$json" | jq -r ".[$i].why // empty")
+    sc=$(echo "$json" | jq -r ".[$i].scope // \"항상\"")
+    so=$(echo "$json" | jq -r ".[$i].source // \"evaluator:auto\"")
+
+    if [ -z "$t" ] || [ -z "$r" ] || [ -z "$ti" ]; then
+      echo "[gotcha-register] skip: missing target/rule_id/title at index $i" >&2
+      continue
+    fi
+    register_one "$t" "$r" "$ti" "$w" "$ri" "$wh" "$sc" "$so"
+  done
+}
+
+# ─────────────────────────────────────────
+# evaluation-*.md 스캔 — ```gotcha_candidates ... ``` JSON fenced block 추출
+# ─────────────────────────────────────────
+scan_evaluations() {
+  if [ ! -d "$ACTIONS_DIR" ]; then return 0; fi
+  local f
+  for f in "$ACTIONS_DIR"/evaluation-*.md; do
+    [ -f "$f" ] || continue
+
+    # Enumerate blocks — simple per-file awk that prints each block into a
+    # uniquely-named temp file. Avoids macOS awk \0 quirks.
+    local blocks_prefix
+    blocks_prefix=$(mktemp -d)
+    awk -v dir="$blocks_prefix" '
+      BEGIN { idx=0 }
+      /^```gotcha_candidates[[:space:]]*$/ { flag=1; buf=""; next }
+      /^```[[:space:]]*$/ && flag {
+        flag=0
+        idx++
+        outfile = sprintf("%s/block-%03d.json", dir, idx)
+        print buf > outfile
+        close(outfile)
+        buf=""
+        next
+      }
+      flag { buf = buf $0 "\n" }
+    ' "$f"
+
+    local blockfile
+    for blockfile in "$blocks_prefix"/block-*.json; do
+      [ -f "$blockfile" ] || continue
+      if jq empty "$blockfile" 2>/dev/null; then
+        register_from_json "$(cat "$blockfile")"
+      else
+        echo "[gotcha-register] skip: invalid JSON block in $(basename "$f")" >&2
+      fi
+    done
+    rm -rf "$blocks_prefix"
+  done
+}
+
+# ─────────────────────────────────────────
+# Parse CLI
+# ─────────────────────────────────────────
+TARGET=""
+RULE_ID=""
+TITLE=""
+WRONG=""
+RIGHT=""
+WHY=""
+SCOPE="항상"
+SOURCE="evaluator:auto"
+MODE="single"
+FROM_JSON=""
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --target)   TARGET="$2"; shift 2 ;;
+    --rule-id)  RULE_ID="$2"; shift 2 ;;
+    --title)    TITLE="$2"; shift 2 ;;
+    --wrong)    WRONG="$2"; shift 2 ;;
+    --right)    RIGHT="$2"; shift 2 ;;
+    --why)      WHY="$2"; shift 2 ;;
+    --scope)    SCOPE="$2"; shift 2 ;;
+    --source)   SOURCE="$2"; shift 2 ;;
+    --from-json) MODE="json"; FROM_JSON="$2"; shift 2 ;;
+    --scan-evaluations) MODE="scan"; shift ;;
+    *) echo "[gotcha-register] unknown arg: $1" >&2; exit 1 ;;
+  esac
+done
+
+case "$MODE" in
+  single)
+    if [ -z "$TARGET" ] || [ -z "$RULE_ID" ] || [ -z "$TITLE" ]; then
+      echo "[gotcha-register] usage: --target X --rule-id Y --title Z [...]" >&2
+      exit 1
+    fi
+    register_one "$TARGET" "$RULE_ID" "$TITLE" "$WRONG" "$RIGHT" "$WHY" "$SCOPE" "$SOURCE"
+    ;;
+  json)
+    if [ ! -f "$FROM_JSON" ]; then echo "[gotcha-register] file not found: $FROM_JSON" >&2; exit 1; fi
+    register_from_json "$(cat "$FROM_JSON")"
+    ;;
+  scan)
+    scan_evaluations
+    ;;
+esac

package/scripts/harness-monitor.sh

@@ -9,6 +9,7 @@
 set -uo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+source "$SCRIPT_DIR/lib/harness-keywait.sh"
 
 # ── Args ──
 # Usage: harness-monitor.sh [project-root] [--team N]
@@ -382,6 +383,7 @@ while true; do
     check_transitions
   fi
 
-  sleep 3
+  printf "${DIM}  [r] refresh  [q] quit${RESET}\033[K\n"
+  wait_or_refresh 3 || true
 done
 

package/scripts/harness-next.sh

@@ -314,6 +314,23 @@ if [ "$agent_status" = "completed" ]; then
   verify_file_ownership "$PROJECT_ROOT" || audit_gate "file-ownership" "warn" "boundary violation detected"
 fi
 
+# ─────────────────────────────────────────
+# Auto Gotcha Registration — Evaluator 완료 직후 evaluation-*.md 스캔
+#   evaluation-*.md 내부의 ```gotcha_candidates``` JSON 블록을 읽어
+#   .harness/gotchas/<target>.md 에 unverified 상태로 등록/dedup.
+# ─────────────────────────────────────────
+case "$current_agent" in
+  evaluator-*)
+    if [ "$agent_status" = "completed" ] || [ "$agent_status" = "failed" ]; then
+      if [ -x "$SCRIPT_DIR/harness-gotcha-register.sh" ]; then
+        bash "$SCRIPT_DIR/harness-gotcha-register.sh" "$PROJECT_ROOT" --scan-evaluations 2>&1 \
+          | grep -E '^\[gotcha-register\]' || true
+        audit_gate "gotcha-register" "scan" "$current_agent"
+      fi
+    fi
+    ;;
+esac
+
 # ─────────────────────────────────────────
 # Run Pre-Eval Gate (if applicable)
 # ─────────────────────────────────────────
@@ -499,19 +516,29 @@ if [ "$next_agent" != "null" ] && [ "$next_agent" != "archive" ] && [ "$agent_st
 
 elif [ "$next_agent" = "archive" ]; then
   audit_log "system" "archive" "start" "sprint-${sprint_num}" "sprint cycle complete"
-  jq -n \
-    --arg from "${current_agent:-evaluator}" \
-    --argjson sprint "$sprint_num" \
-    --arg timestamp "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
-    '{
-      from: $from,
-      to: "archive",
-      prompt: "Sprint 문서를 아카이브하세요.\n.harness/actions/의 스프린트 문서를 .harness/archive/sprint-NNN/으로 이동합니다.\n.harness/handoff.json을 읽고 sprint 번호를 확인하세요.",
-      sprint: $sprint,
-      model: "opus",
-      thinking_mode: null,
-      timestamp: $timestamp
-    }' > "$HANDOFF"
+
+  # ── Auto-archive: run archive script synchronously ──
+  # harness-archive.sh moves .harness/actions/* to .harness/archive/D-NNN/S-NNN/
+  # and resets progress.json. On next user prompt the flow starts fresh as a new dispatch.
+  if bash "$SCRIPT_DIR/harness-archive.sh" "$PROJECT_ROOT"; then
+    audit_log "system" "archive" "complete" "sprint-${sprint_num}" "auto-archived"
+  else
+    echo "  ⚠ archive script failed — falling back to manual handoff" >&2
+    audit_log "system" "archive" "fail" "sprint-${sprint_num}" "script failed"
+    jq -n \
+      --arg from "${current_agent:-evaluator}" \
+      --argjson sprint "$sprint_num" \
+      --arg timestamp "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+      '{
+        from: $from,
+        to: "archive",
+        prompt: "Sprint 문서를 아카이브하세요. harness-archive.sh 가 실패했습니다 — 수동으로 .harness/actions/* 를 .harness/archive/D-NNN/S-NNN/ 로 이동하세요.",
+        sprint: $sprint,
+        model: "opus",
+        thinking_mode: null,
+        timestamp: $timestamp
+      }' > "$HANDOFF"
+  fi
 
 else
   echo '{}' > "$HANDOFF"

package/scripts/harness-prompt-history.sh

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

package/scripts/harness-queue-manager.sh

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

package/scripts/harness-session-start.sh

@@ -83,6 +83,7 @@ fi
 # ─────────────────────────────────────────
 if [ "$sprint_status" = "init" ]; then
   echo "# Harness ready — say \"하네스 엔지니어링 시작\" or /harness-dispatcher"
+  echo "# 기본은 Solo 모드. 병렬 3팀 실행을 원하면 Planner 완료 후 /harness-team."
   exit 0
 fi
 

package/scripts/lib/harness-keywait.sh

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

package/skills/dispatcher/SKILL.md

@@ -42,6 +42,18 @@ jq '.agent_status = "completed" | .completed_agents += ["planner"]'   .harness/p
      - Gotcha 교정 후 재작업 → `failure.retry_target` (해당 에이전트)
    - `pipeline` → 선택된 파이프라인 (FULLSTACK/FE-ONLY/BE-ONLY)
    - `sprint.number` → `1`, `sprint.status` → `"in_progress"` (신규 파이프라인인 경우에만)
+   - **신규 파이프라인인 경우** `dispatch.id` 가 `null` 이면 counter 를 올리고 새 ID 를 발급 (v5.7+):
+     ```bash
+     # dispatch.id 가 이미 있으면 기존 dispatch 유지, 없으면 새로 발급
+     cur=$(jq -r '.dispatch.id // ""' .harness/progress.json)
+     if [ -z "$cur" ]; then
+       next=$(jq -r '((.dispatch.counter // 0) + 1)' .harness/progress.json)
+       new_id=$(printf 'D-%03d' "$next")
+       bash scripts/harness-progress-set.sh . \
+         ".dispatch.counter = $next | .dispatch.id = \"$new_id\""
+     fi
+     ```
+     아카이빙 후 `dispatch.id` 는 `null` 로 리셋되므로, 다음 dispatcher 실행 시 새 D-NNN 이 할당된다.
 2. `.harness/progress.log`에 요약 한 줄 추가
 3. **STOP. 다음 에이전트를 직접 호출하지 않는다.**
 4. 출력: `"✓ Dispatcher 완료. bash scripts/harness-next.sh 실행하여 다음 단계 확인."`
@@ -140,6 +152,28 @@ AGENTS.md 비하네스  → 기존 백업 + 리빌드
 
 `.harness/actions/pipeline.json` 생성 → 사용자 확인 → Session Boundary Protocol On Complete 실행
 
+### Mode Recommendation (v5.7.1+)
+
+⚠️ **Dispatcher → Planner 전환 시에는 mode 질문을 하지 않는다.** Planner 는 mode 와 무관한 단일 실행이다. 과거의 "harness-solo 를 입력하세요" 안내는 제거.
+
+파이프라인이 확정되면 (Planner 호출 직전) **단 한 문단** 으로 Mode 추천을 출력하되, 응답을 기다리지 않고 **default=solo 로 그대로 진행**한다. 사용자가 team 을 원하면 언제든 `/harness-team` 으로 전환 가능.
+
+추천 로직:
+- Planner 가 feature-list.json 을 확정한 뒤 `features.length >= 3` 이고 서로 의존성이 낮으면 → "Team 모드 권장" 안내
+- `features.length < 3` 또는 단일 feature 연속 작업 → "Solo 모드 권장" 안내
+- Dispatcher 단계에서는 feature 수를 모를 수 있으므로 **기본은 Solo 진행**, Planner 완료 후 자동으로 재평가
+
+출력 예:
+```
+Pipeline: FULLSTACK 확정. Solo 모드로 자동 진행합니다.
+(병렬 3팀 실행을 원하면 Planner 완료 후 /harness-team 입력)
+```
+
+**금지**:
+- "solo 입력하세요 / team 입력하세요" 식의 선택 강요
+- mode 결정을 기다리며 Planner 호출을 보류하는 것
+- 이미 mode 가 설정된 상태(`progress.json.mode` 존재)에서 재질문하는 것
+
 ### evaluator_chain 필드 (모든 파이프라인 필수)
 
 `pipeline.json` 에 **`evaluator_chain`** 배열을 기록한다. `config.json.flow.pipeline_selection.evaluator_chains.<pipeline>` 의 값을 복사:

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

@@ -158,6 +158,34 @@ Cross-Validation 데이터 블록 포함 (Functional/Visual 이 참조):
 }
 ```
 
+## Auto Gotcha Registration — v5.7.1+
+
+**필수 emission**: `actions/evaluation-code-quality.md` 끝부분에 `gotcha_candidates` JSON 블록을 반드시 포함 (후보 없으면 `[]`). `harness-next.sh` 가 Evaluator 완료 직후 이 블록을 스캔해 자동 등록한다.
+
+````
+```gotcha_candidates
+[
+  {
+    "target": "generator-backend",
+    "rule_id": "be-any-type-leak",
+    "title": "서비스 레이어 any 남용",
+    "wrong": "UserService.findAll() 반환 타입을 any[] 로 선언",
+    "right": "api-contract.json 의 DTO 타입을 재사용하거나 shared-dto 에 정의",
+    "why": "C4 Type Safety 축은 25% 가중. evidence 없는 any 는 Score 0.",
+    "scope": "모든 BE service/controller 레이어",
+    "source": "evaluator-code-quality:F-002"
+  }
+]
+```
+````
+
+등록 규칙:
+- `target`: 실수를 반복할 대상 에이전트 (`generator-backend`, `generator-frontend`, `planner` 등).
+- `rule_id`: dedup 키 (동일 rule_id 는 Occurrences +1, 본문 미변경).
+- 신규 항목은 `Status: unverified`. Planner 리뷰 후 `verified` 승격.
+- **FAIL 시**: 실패 근본 원인 1건 이상을 반드시 등록.
+- **PASS 시**: 발견된 경미한 위반이 있으면 등록 (스코어 미반영이지만 반복 방지).
+
 ## Adversarial Rules
 
 - "동작하니 PASS" 금지. 여기서는 구조를 본다.

package/skills/evaluator-functional/SKILL.md

@@ -137,16 +137,38 @@ Evaluator 는 스택마다 다른 검증 도구를 가진다. `scan-result.json.
    - false → evaluation-functional.md 에 "MANUAL_REQUIRED: {manual_check}" 기록, Visual 은 __skip__
 ```
 
-### Auto Gotcha Registration (안티패턴 자동 등록)
+### Auto Gotcha Registration (안티패턴 + 평가 실패 자동 등록) — v5.7.1+
+
+**필수 emission**: `actions/evaluation-functional.md` 끝부분에 아래 fenced JSON 블록을 반드시 포함한다 (후보 없으면 빈 배열 `[]`). `harness-next.sh` 가 Evaluator 완료 직후 이 블록을 스캔해 `scripts/harness-gotcha-register.sh` 로 자동 등록한다.
+
+````
+```gotcha_candidates
+[
+  {
+    "target": "generator-frontend",
+    "rule_id": "fe-console-error-ignored",
+    "title": "콘솔 JS 에러 방치",
+    "wrong": "렌더 직후 발생하는 TypeError 를 수정하지 않고 PASS 주장",
+    "right": "콘솔 JS 에러 0 이 될 때까지 수정 후 재제출",
+    "why": "Evaluator-Functional 콘솔 청결 축은 15% 가중 하드 임계 (0개)",
+    "scope": "모든 FE Feature",
+    "source": "evaluator-functional:F-003"
+  }
+]
+```
+````
 
-`validation.anti_pattern_rules` 실행에서 위반 1건 이상 발견 시 — Dispatcher 경유로 자동 gotcha 등록:
+등록 규칙:
+- `target`: 실수를 반복할 **대상 에이전트** (예: `generator-frontend`, `generator-backend`, `planner`). 본인(`evaluator-*`) 대상도 가능.
+- `rule_id`: 전역 유일 식별자. 동일 rule_id 는 Occurrences 증가 + Last-Seen 갱신 (본문 미변경).
+- `source`: 출처 — `<agent>:<feature-id>` 형식 권장.
+- 신규 항목은 `Status: unverified` 로 기록. Planner 리뷰 후 수동으로 `verified` 승격.
+- 대상 파일: `.harness/gotchas/<target>.md` (스택별 파일 필요 시 `<target>-<stack>.md` 를 `target` 에 명시).
 
-- 대상 파일: `.harness/gotchas/generator-<role>-<stack>.md` (없으면 생성)
-- 항목 포맷: `### [G-NNN] <rule_id>` / severity / occurrences / last_seen(file:line) / snippet / source feature
-- 중복 rule_id: Occurrences 카운터 +1 + last_seen 업데이트
-- 상세 계약: `api-contract.json.contracts["gotcha_register_interface"]`
+**FAIL 시**: 실패 근본 원인 1건 이상을 반드시 candidate 로 등록 (중복 실수 방지가 목적).
+**PASS 시**: 발견된 안티패턴/경미한 위반이 있으면 등록 (스코어에는 반영 안 됐지만 반복 방지).
 
-이 메커니즘이 작동하려면 Dispatcher 의 "Auto Gotcha Registration" 섹션을 참고하라.
+Dispatcher 경유 수동 등록은 여전히 가능하지만, **이 자동 파이프라인이 기본 경로**다.
 
 ## Evaluation Steps
 

package/skills/evaluator-visual/SKILL.md

@@ -121,6 +121,34 @@ jq '.agent_status = "completed" | .completed_agents += ["planner"]'   .harness/p
 
 **어떤 차원이든 하드 임계값 미달 → FAIL**
 
+## Auto Gotcha Registration — v5.7.1+
+
+**필수 emission**: `actions/evaluation-visual.md` 끝부분에 `gotcha_candidates` JSON 블록을 반드시 포함 (후보 없으면 `[]`). `harness-next.sh` 가 Evaluator 완료 직후 이 블록을 스캔해 자동 등록한다.
+
+````
+```gotcha_candidates
+[
+  {
+    "target": "generator-frontend",
+    "rule_id": "fe-contrast-fail",
+    "title": "텍스트 대비 WCAG AA 미달",
+    "wrong": "버튼 #888 on #aaa — 3.0:1 (AA 4.5:1 미만)",
+    "right": "primary 버튼은 body 컬러 대비 4.5:1 이상 보장. Tailwind tokens 활용.",
+    "why": "접근성은 Evaluator-Visual 하드 임계",
+    "scope": "모든 인터랙티브 엘리먼트",
+    "source": "evaluator-visual:F-004"
+  }
+]
+```
+````
+
+등록 규칙:
+- `target`: 실수를 반복할 대상 에이전트 (일반적으로 `generator-frontend`, 디자인 토큰 결함은 `planner`).
+- `rule_id`: dedup 키.
+- 신규 항목은 `Status: unverified`. Planner 리뷰 후 `verified` 승격.
+- **FAIL 시**: 실패 근본 원인 1건 이상 반드시 등록.
+- **PASS 시**: 감지된 경미한 디자인 편차가 있으면 등록 (반복 방지).
+
 ## After Evaluation
 
 - **PASS** → Session Boundary Protocol On Complete (PASS) 실행