@walwal-harness/cli 5.7.0 → 5.7.1

package/bin/init.js

@@ -1017,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/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.7.0",
+  "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-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-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)
 # ─────────────────────────────────────────

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/skills/dispatcher/SKILL.md

@@ -152,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) 실행