@walwal-harness/cli 5.8.1 → 5.9.0

package/commands/harness-team.md

@@ -161,7 +161,35 @@ ORCHESTRATION LOOP:
 
 #### Step 4a: Merge + Unblock (PASS 처리)
 
-Worker가 PASS로 반환되면:
+**⚠ HARD GATE — Runtime Bug 검출 시 PASS 처리 금지**
+
+Worker 가 PASS 로 반환했더라도, 보고서에 다음 신호가 하나라도 포함되어 있으면 **PASS 처리하지 말고 즉시 FAIL 로 전환**한다. carry-over / 다음 sprint 미루기 절대 금지 — 견고한 기반 위에서만 다음 sprint 로 진행한다.
+
+검출 시그널 (worker 반환 텍스트 검색):
+- "runtime bug", "런타임 버그", "런타임 에러", "runtime error"
+- "RSC", "Client Component" 경계 위반 (use client 누락 등)
+- "not-found", "error.tsx", "loading.tsx" 누락/오류
+- "typed-routes", "TypeScript route" 미스매치
+- "console error", "uncaught", "Hydration error", "hydration mismatch"
+- 그 외 worker 가 자신의 결과를 "carry-over", "다음 sprint 에서 처리", "추후 수정", "follow-up" 으로 표현하는 모든 케이스
+
+위 신호 검출 시 처리:
+```bash
+# 1) PASS 가 아니라 FAIL 로 큐 업데이트
+bash scripts/harness-queue-manager.sh fail {FEATURE_ID} .
+
+# 2) 즉시 같은 feature 를 재투입 (worktree 재사용 또는 새 worker)
+#    Agent 프롬프트에 worker 가 보고한 버그 목록을 명시하고
+#    "이 sprint 안에서 fix 완료될 때까지 done 처리 금지" 강제
+```
+
+3) Sprint 전환 게이트: `next-sprint` 호출 전에 carry-over / known-bug 가 0 인지 반드시 확인. 1 건이라도 남아있으면 sprint advance 금지 — 같은 sprint 안에서 fix sprint 를 한 사이클 더 돈다.
+
+이 룰을 위반한 사례: F-209 평가에서 "monitoring page RSC/CC, not-found.tsx, sidebar-nav typed-routes" 3 개 런타임 버그를 인지한 채 PASS 처리하고 Sprint 4 carry-over 로 미룬 적이 있다. 사용자 명시: "오류가 있는 것을 인지한 채로 스프린트를 넘어가는 행위는 절대 용납할 수 없다."
+
+---
+
+위 hard gate 를 통과한(=깨끗한 PASS) 경우에만:
 
 1. **Worktree branch 확인**: Agent 반환 결과에서 worktree path와 branch 확인
 2. **Main에 merge**:
@@ -169,7 +197,16 @@ Worker가 PASS로 반환되면:
    git merge {BRANCH_NAME} --no-edit
    ```
    - 충돌 시: 자동 해결 시도 → 실패 시 사용자 개입 요청
-3. **Queue 업데이트** (unblock 포함):
+3. **동적 Gotcha/Convention 등록** (merge 직후 필수):
+   ```bash
+   # worker 가 작성한 evaluation-*.md / gen-report-*.md 의
+   # gotcha_candidates / convention_candidates 블록을 모두 dedup append
+   bash scripts/harness-gotcha-register.sh . --scan-all
+   ```
+   다음 worker spawn 전에 갱신된 gotchas/conventions 가 file system 에 반영되어야 함.
+   실수가 sprint 중에 등록되지 않으면 다음 worker 가 같은 실수 반복.
+
+4. **Queue 업데이트** (unblock 포함):
    ```bash
    bash scripts/harness-queue-manager.sh pass {FEATURE_ID} .
    ```

package/gotchas/evaluator-code-quality.md

@@ -19,3 +19,13 @@ docmeta:
 > Dispatcher가 관리. Evaluator-Code-Quality는 세션 시작 시 이 파일을 읽고 같은 실수를 반복하지 않습니다.
 
 <!-- 항목이 추가되면 아래에 기록됩니다 -->
+
+## [G-001] 런타임 버그 인지 후 PASS 판정 금지 (verified · 2026-04-27)
+
+**Status**: verified · **Severity**: HIGH
+
+**규칙**: Code-quality eval 단계에서 SSR/RSC↔CC 경계 위반, 잘못된 라우트 타입, missing not-found/error.tsx 등 **런타임에 깨질 정적 결함**을 발견하면 즉시 FAIL. "스타일/구조 문제만 본다" 는 자기 합리화로 런타임 결함을 functional 단계로 넘기지 말 것.
+
+**Why**: 사용자 명시 — "오류가 있는 것을 인지한 채로 스프린트를 넘어가는 행위는 절대 용납할 수 없다." Code-quality 가 정적 분석으로 잡을 수 있었던 결함을 통과시키면 evaluator chain 전체가 신뢰성을 잃는다.
+
+**How to apply**: tsc/eslint 외에도 Next.js App Router 규칙 (use client 경계, typed routes), 라우트 세그먼트 필수 파일 (not-found/error/loading) 누락 여부를 정적으로 검사. 1 건이라도 발견 시 VERDICT=FAIL, retry_target=결함 위치 Generator.

package/gotchas/evaluator-functional.md

@@ -1,5 +1,42 @@
+---
+docmeta:
+  id: evaluator-functional-gotchas
+  title: Gotchas — Evaluator-Functional
+  type: input
+  createdAt: 2026-04-08T00:00:00Z
+  updatedAt: 2026-04-27T00:00:00Z
+  source:
+    producer: user
+    skillId: harness-dispatcher
+  inputs: []
+  tags: [harness, gotcha, evaluator, evaluator-functional]
+---
+
 # Gotchas — Evaluator-Functional
 
 > Dispatcher가 관리. Evaluator-Functional은 세션 시작 시 이 파일을 읽고 같은 실수를 반복하지 않습니다.
 
 <!-- 항목이 추가되면 아래에 기록됩니다 -->
+
+## [G-001] 런타임 버그 인지 후 PASS 판정 금지 (verified · 2026-04-27)
+
+**Status**: verified
+**Severity**: HIGH
+**Occurrences**: 1+ (실제 사례: harness-clue Sprint 3 F-209)
+
+**규칙**: Evaluator (functional / visual / code-quality 모두) 가 평가 중 런타임 버그를 발견했거나 worker 가 보고서에 런타임 버그를 명시한 경우, **PASS 판정 절대 금지**. carry-over / 다음 sprint 처리 / follow-up 으로 미루기도 금지. 같은 sprint 안에서 fix 완료 후에만 PASS.
+
+**검출 시그널** (eval 자체 + worker report 둘 다 스캔):
+- "runtime bug", "런타임 버그/에러", "runtime error"
+- RSC ↔ Client Component 경계 위반 (`use client` 누락 등)
+- `not-found.tsx`, `error.tsx`, `loading.tsx` 누락/오류
+- typed-routes / TypeScript route 타입 미스매치
+- Hydration error, Hydration mismatch
+- 콘솔 uncaught error, unhandled promise rejection
+- worker 가 자기 결과를 "carry-over", "다음 sprint", "추후", "follow-up" 으로 표현
+
+**처리**: 위 시그널 1 건 이상 → VERDICT=FAIL, score 무관, retry_target = 결함 위치 Generator. 점수가 2.80+ 이어도 FAIL 강제 (Adversarial Rule).
+
+**Why**: 사용자 명시 — "오류가 있는 것을 인지한 채로 스프린트를 넘어가는 행위는 절대 용납할 수 없다. 견고하게 기반을 다져나가야 한다."
+
+**How to apply**: Eval 종료 직전 자기 보고서 + Generator 보고서를 위 키워드로 grep. 1 건이라도 매치하면 verdict 를 FAIL 로 강제 변환하고 evaluation-*.md 의 결론 섹션에 "Hard Gate G-001 위반: <검출 키워드> — 같은 sprint 내 fix 후 재평가 필요" 명시.

package/gotchas/evaluator-visual.md

@@ -1,5 +1,31 @@
+---
+docmeta:
+  id: evaluator-visual-gotchas
+  title: Gotchas — Evaluator-Visual
+  type: input
+  createdAt: 2026-04-08T00:00:00Z
+  updatedAt: 2026-04-27T00:00:00Z
+  source:
+    producer: user
+    skillId: harness-dispatcher
+  inputs: []
+  tags: [harness, gotcha, evaluator, evaluator-visual]
+---
+
 # Gotchas — Evaluator-Visual
 
 > Dispatcher가 관리. Evaluator-Visual은 세션 시작 시 이 파일을 읽고 같은 실수를 반복하지 않습니다.
 
 <!-- 항목이 추가되면 아래에 기록됩니다 -->
+
+## [G-001] 런타임 버그 인지 후 PASS 판정 금지 (verified · 2026-04-27)
+
+**Status**: verified · **Severity**: HIGH
+
+**규칙**: Visual eval 중 콘솔 에러/Hydration mismatch/RSC↔CC 경계 위반/렌더 실패가 한 번이라도 관찰되면 PASS 절대 금지. 스크린샷이 멀쩡해 보여도 console.error 가 1 건 이상이면 FAIL. carry-over/follow-up 으로 미루기 금지.
+
+**검출 시그널**: console error/warning, Hydration error, "use client" 누락, not-found/error.tsx 미렌더, layout shift 비정상, 404/500 응답.
+
+**처리**: VERDICT=FAIL, retry_target=generator-frontend, evaluation-visual.md 결론에 "Hard Gate G-001 위반" 명시. 같은 sprint 내 fix 완료 후에만 재평가.
+
+**Why**: 사용자 명시 — "오류가 있는 것을 인지한 채로 스프린트를 넘어가는 행위는 절대 용납할 수 없다."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@walwal-harness/cli",
-  "version": "5.8.1",
+  "version": "5.9.0",
   "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

@@ -171,43 +171,173 @@ register_from_json() {
 }
 
 # ─────────────────────────────────────────
-# evaluation-*.md 스캔 — ```gotcha_candidates ... ``` JSON fenced block 추출
+# Convention 등록 — .harness/conventions/<scope>.md 에 [C-NNN] entry append
+#   $1: scope (shared, generator-backend, generator-frontend, ... — 파일명 base)
+#   $2: rule_id (dedup key)
+#   $3: title
+#   $4: rule (긍정 가이드 본문 — "X 는 항상 Y 로")
+#   $5: why
+#   $6: source
+# ─────────────────────────────────────────
+CONVENTIONS_DIR="$PROJECT_ROOT/.harness/conventions"
+register_convention_one() {
+  local scope="$1" rule_id="$2" title="$3" rule="$4" why="$5" source="$6"
+  mkdir -p "$CONVENTIONS_DIR"
+  local file="$CONVENTIONS_DIR/${scope}.md"
+
+  if [ ! -f "$file" ]; then
+    cat > "$file" <<EOF
+# Conventions — ${scope}
+
+> Dispatcher가 관리. 긍정 가이드("~를 사용해", "항상 ~") 자동 등록.
+
+EOF
+  fi
+
+  # dedup: 같은 rule_id 가 있으면 해당 [C-NNN] 블록의 Occurrences +1, Last-Seen 갱신
+  if grep -qE "<!-- rule_id: ${rule_id} -->" "$file" 2>/dev/null; then
+    awk -v rid="$rule_id" -v today="$TODAY" '
+      BEGIN { in_block = 0 }
+      /^### \[C-[0-9]+\].*<!-- rule_id: / {
+        in_block = ($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] convention/${scope}: dedup ${rule_id} (occurrence bumped)"
+    return 0
+  fi
+
+  # 신규 — 다음 [C-NNN] 번호 할당 (set -e 회피: || true)
+  local last_n
+  last_n=$(grep -oE '\[C-[0-9]+\]' "$file" 2>/dev/null | grep -oE '[0-9]+' | sort -n | tail -1 || true)
+  last_n=${last_n:-0}
+  local next_n=$(printf "%03d" $((last_n + 1)))
+
+  cat >> "$file" <<EOF
+
+### [C-${next_n}] ${title}  <!-- rule_id: ${rule_id} -->
+- **Status**: unverified
+- **Date**: ${TODAY}
+- **Source**: ${source}
+- **Rule**: ${rule}
+- **Why**: ${why}
+- **Occurrences**: 1
+- **Last-Seen**: ${TODAY}
+EOF
+
+  echo "[gotcha-register] convention/${scope}: registered C-${next_n} (${rule_id}) — unverified"
+}
+
+register_conventions_from_json() {
+  local json="$1"
+  local count
+  count=$(echo "$json" | jq 'length' 2>/dev/null || echo 0)
+  [ "$count" -eq 0 ] && return 0
+  local i
+  for ((i=0; i<count; i++)); do
+    local sc r ti ru wh so
+    sc=$(echo "$json" | jq -r ".[$i].scope // \"shared\"")
+    r=$(echo "$json"  | jq -r ".[$i].rule_id // empty")
+    ti=$(echo "$json" | jq -r ".[$i].title // empty")
+    ru=$(echo "$json" | jq -r ".[$i].rule // empty")
+    wh=$(echo "$json" | jq -r ".[$i].why // empty")
+    so=$(echo "$json" | jq -r ".[$i].source // \"agent:auto\"")
+    if [ -z "$r" ] || [ -z "$ti" ] || [ -z "$ru" ]; then
+      echo "[gotcha-register] convention skip: missing rule_id/title/rule at index $i" >&2
+      continue
+    fi
+    register_convention_one "$sc" "$r" "$ti" "$ru" "$wh" "$so"
+  done
+}
+
+# ─────────────────────────────────────────
+# 단일 파일에서 fenced block 추출 (block_tag 인자로 종류 지정)
+#   $1: file path · $2: block tag (gotcha_candidates 또는 convention_candidates)
+# stdout 으로 각 block JSON 을 한 줄씩 출력 (\0 구분자)
+# ─────────────────────────────────────────
+extract_blocks() {
+  local file="$1" tag="$2"
+  local blocks_prefix
+  blocks_prefix=$(mktemp -d)
+  awk -v dir="$blocks_prefix" -v tag="$tag" '
+    BEGIN { idx=0; flag=0; buf="" }
+    $0 ~ ("^```" tag "[[: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" }
+  ' "$file"
+  echo "$blocks_prefix"
+}
+
+process_blocks_in_file() {
+  local file="$1"
+  # gotcha_candidates
+  local g_dir
+  g_dir=$(extract_blocks "$file" "gotcha_candidates")
+  local b
+  for b in "$g_dir"/block-*.json; do
+    [ -f "$b" ] || continue
+    if jq empty "$b" 2>/dev/null; then
+      register_from_json "$(cat "$b")"
+    else
+      echo "[gotcha-register] skip: invalid gotcha_candidates JSON in $(basename "$file")" >&2
+    fi
+  done
+  rm -rf "$g_dir"
+
+  # convention_candidates
+  local c_dir
+  c_dir=$(extract_blocks "$file" "convention_candidates")
+  for b in "$c_dir"/block-*.json; do
+    [ -f "$b" ] || continue
+    if jq empty "$b" 2>/dev/null; then
+      register_conventions_from_json "$(cat "$b")"
+    else
+      echo "[gotcha-register] skip: invalid convention_candidates JSON in $(basename "$file")" >&2
+    fi
+  done
+  rm -rf "$c_dir"
+}
+
+# ─────────────────────────────────────────
+# evaluation-*.md 스캔 — ```gotcha_candidates``` + ```convention_candidates``` 둘 다
 # ─────────────────────────────────────────
 scan_evaluations() {
-  if [ ! -d "$ACTIONS_DIR" ]; then return 0; fi
+  [ -d "$ACTIONS_DIR" ] || return 0
   local f
   for f in "$ACTIONS_DIR"/evaluation-*.md; do
     [ -f "$f" ] || continue
+    process_blocks_in_file "$f"
+  done
+}
 
-    # 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"
+# ─────────────────────────────────────────
+# 모든 worker report 스캔 — evaluation-*.md + gen-report-*.md + lead-report-*.md
+# Generator 는 gen-report-{F-ID}.md 작성, Lead 는 lead-report-{date}.md 작성 가능
+# ─────────────────────────────────────────
+scan_all() {
+  [ -d "$ACTIONS_DIR" ] || return 0
+  local f
+  for f in "$ACTIONS_DIR"/evaluation-*.md "$ACTIONS_DIR"/gen-report-*.md "$ACTIONS_DIR"/lead-report-*.md; do
+    [ -f "$f" ] || continue
+    process_blocks_in_file "$f"
   done
 }
 
@@ -237,6 +367,7 @@ while [ $# -gt 0 ]; do
     --source)   SOURCE="$2"; shift 2 ;;
     --from-json) MODE="json"; FROM_JSON="$2"; shift 2 ;;
     --scan-evaluations) MODE="scan"; shift ;;
+    --scan-all) MODE="scan-all"; shift ;;
     *) echo "[gotcha-register] unknown arg: $1" >&2; exit 1 ;;
   esac
 done
@@ -256,4 +387,7 @@ case "$MODE" in
   scan)
     scan_evaluations
     ;;
+  scan-all)
+    scan_all
+    ;;
 esac

package/scripts/harness-next.sh

@@ -320,12 +320,14 @@ fi
 #   .harness/gotchas/<target>.md 에 unverified 상태로 등록/dedup.
 # ─────────────────────────────────────────
 case "$current_agent" in
-  evaluator-*)
+  evaluator-*|generator-*)
     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 \
+        # --scan-all 로 evaluation-*.md + gen-report-*.md + lead-report-*.md 의
+        # gotcha_candidates / convention_candidates 블록 모두 동적 등록
+        bash "$SCRIPT_DIR/harness-gotcha-register.sh" "$PROJECT_ROOT" --scan-all 2>&1 \
           | grep -E '^\[gotcha-register\]' || true
-        audit_gate "gotcha-register" "scan" "$current_agent"
+        audit_gate "gotcha-register" "scan-all" "$current_agent"
       fi
     fi
     ;;

package/skills/_shared/dynamic-registration.md

@@ -0,0 +1,120 @@
+---
+docmeta:
+  id: dynamic-registration
+  title: 동적 Gotcha / Convention 등록 — 모든 worker mandatory
+  type: input
+  createdAt: 2026-04-27T00:00:00Z
+  updatedAt: 2026-04-27T00:00:00Z
+  source:
+    producer: user
+    skillId: harness
+  inputs: []
+  tags: [harness, gotcha, convention, dynamic-registration, mandatory]
+---
+
+# 동적 Gotcha / Convention 등록 — 모든 worker mandatory
+
+모든 Generator / Evaluator / Lead 는 자기 작업 결과물(`evaluation-*.md` / `gen-report-*.md` / `lead-report-*.md`) 끝에 **두 개의 fenced JSON 블록**을 반드시 포함한다. `harness-next.sh` 와 Team mode Lead 가 작업 직후 자동으로 `harness-gotcha-register.sh --scan-all` 을 호출하여 두 블록을 dedup append 한다.
+
+**왜 mandatory 인가**: 사용자 명시 — "Gen/Eval 이 발견한 패턴은 메뉴얼로 시키기 전에 동적으로 등록되어야 한다. 자동으로 패턴화되는 이슈는 등록하라." 한 번 발견된 실수가 다음 sprint 에서 반복되지 않게 하려면 발견자가 그 자리에서 등록하는 것이 유일한 closure.
+
+**금지**: 두 블록 중 하나라도 누락된 채로 작업 종료. 비어 있어도 `[]` 로 명시 (블록 자체 생략 금지).
+
+---
+
+## 1) gotcha_candidates — 부정 가이드 (실수 패턴)
+
+**누가 등록**:
+- Evaluator: 평가 중 발견한 generator 의 반복 가능한 결함
+- Generator: 자기 작업 중 한 번 시도했다가 깨졌던 접근, 자체 fix 한 코드 실수
+- Lead (Team mode): worker 보고서들에서 N 회 반복되는 패턴 (≥2 occurrences 권장)
+
+**검출 기준** (하나라도 해당):
+- 같은 sprint 내 다른 feature 에서도 재발할 가능성이 있는 결함
+- generator 가 자주 빠뜨리는 케이스 (RSC↔CC 경계, schema 누락, missing not-found.tsx 등)
+- spec/contract 위반 패턴
+- AC 부분 통과 / Hard Gate 위반 사유
+- lint/type 이 한 번에 안 잡힌 케이스 (정적 분석으로 못 잡는 결함)
+
+**스키마**:
+```gotcha_candidates
+[
+  {
+    "target": "generator-frontend",
+    "rule_id": "rsc-cc-boundary-monitoring",
+    "title": "Server Component 에서 useState/useEffect 호출",
+    "wrong": "app/monitoring/page.tsx 에 'use client' 없이 hook 사용 → 빌드 통과해도 런타임에 깨짐",
+    "right": "client-side state 사용 시 파일 최상단에 'use client' 명시. 또는 server component 로 유지하면서 client 부분만 분리.",
+    "why": "Next.js App Router 의 RSC↔CC 경계는 정적 분석으로 100% 안 잡힘. F-209 에서 발견.",
+    "scope": "app/**/page.tsx, app/**/layout.tsx",
+    "source": "evaluator-functional:F-209"
+  }
+]
+```
+
+비어 있으면:
+```gotcha_candidates
+[]
+```
+
+필수 필드: `target`, `rule_id`, `title`. 권장 필드: `wrong`, `right`, `why`, `scope`, `source`.
+
+`target` 가능 값: `planner`, `dispatcher`, `brainstorming`, `generator-backend`, `generator-frontend`, `generator-frontend-flutter`, `evaluator-code-quality`, `evaluator-functional`, `evaluator-visual`, `evaluator-functional-flutter`.
+
+`rule_id` 는 dedup key — 같은 rule_id 가 이미 있으면 Occurrences +1 만 증가하고 본문은 안 바뀜. **kebab-case 짧고 의미 있는 식별자**.
+
+---
+
+## 2) convention_candidates — 긍정 가이드 (반복 가능한 best practice)
+
+**누가 등록**:
+- Evaluator: 평가 중 확립된 반복 가능한 모범 사례
+- Generator: 작업 중 적용한 일관된 패턴 (다른 feature 에 모방되어야 하는)
+- Lead: sprint 전반에서 합의된 룰
+
+**검출 기준**:
+- 같은 sprint 의 다른 feature 가 모방해야 할 패턴
+- API 계약 / 폴더 구조 / 명명 규칙 관련 결정
+- 사용자가 "이렇게 해" 라고 한 한 번의 발언이 평가/생성에서 일반화 가능한 경우
+
+**스키마**:
+```convention_candidates
+[
+  {
+    "scope": "generator-frontend",
+    "rule_id": "route-segment-files",
+    "title": "App Router 세그먼트 필수 파일 세트",
+    "rule": "모든 app/**/page.tsx 는 같은 폴더에 not-found.tsx, error.tsx, loading.tsx 를 함께 배치한다.",
+    "why": "Next.js 의 segment-level 에러/로딩 처리. 누락 시 default 흰 화면 노출. F-209 평가에서 표준화 결정.",
+    "source": "evaluator-functional:F-209"
+  }
+]
+```
+
+비어 있으면:
+```convention_candidates
+[]
+```
+
+필수 필드: `rule_id`, `title`, `rule`. 권장 필드: `scope`, `why`, `source`.
+
+`scope` 가능 값: `shared` (전체 공통), `generator-backend`, `generator-frontend`, `evaluator-*`, `planner`. 미지정 시 `shared`.
+
+---
+
+## 3) 등록 결과 확인
+
+작업 완료 후 다음 명령으로 등록된 항목 확인 가능:
+```bash
+bash scripts/harness-gotcha-register.sh . --scan-all  # 수동 재스캔
+ls .harness/gotchas/ .harness/conventions/             # 누적 결과
+tail -20 .harness/progress.log | grep gotcha-register  # 등록 로그
+```
+
+## 4) Team mode 추가 룰
+
+Team mode 에서 Lead 는 worker PASS/FAIL 처리 직후 (merge 전) 다음을 실행한다:
+```bash
+bash scripts/harness-gotcha-register.sh . --scan-all
+```
+이로써 worker 가 작성한 두 블록이 즉시 누적되며, 다음 worker spawn 시 새 worker 가 갱신된 gotchas/conventions 를 startup 에 읽어 같은 실수를 반복하지 않는다.

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

@@ -206,3 +206,13 @@ Cross-Validation 데이터 블록 포함 (Functional/Visual 이 참조):
 
 - **PASS** → Session Boundary Protocol On Complete (PASS) 실행
 - **FAIL** → Session Boundary Protocol On Fail 실행
+
+## ⚠ MANDATORY — 동적 Gotcha / Convention 등록
+
+evaluation-code-quality.md 의 끝에 **반드시 `gotcha_candidates` 와 `convention_candidates` fenced JSON 블록**을 작성한다 (비어 있으면 `[]`). harness-next.sh / Team Lead 가 자동 스캔하여 `.harness/gotchas/` `.harness/conventions/` 에 dedup append.
+
+**Code-quality 특화 검출 대상**:
+- 정적 분석으로 잡을 수 있는데 generator 가 빠뜨린 패턴 → `gotcha_candidates`
+- 코드 구조/명명/import 정렬 등 일관 룰 → `convention_candidates`
+
+상세 스키마 / 예시 / 필수 필드 → [공통 가이드 — dynamic-registration](../_shared/dynamic-registration.md)

package/skills/evaluator-functional/SKILL.md

@@ -204,3 +204,68 @@ Playwright 도구 → [도구 레퍼런스](references/playwright-tools.md)
 
 - **PASS** → Session Boundary Protocol On Complete (PASS) 실행
 - **FAIL** → Session Boundary Protocol On Fail 실행
+
+## ⚠ MANDATORY — 동적 Gotcha / Convention 등록 (모든 평가에서 필수)
+
+evaluation-functional.md 의 끝에 **반드시 두 개의 fenced JSON 블록**을 작성한다. 비어 있어도 `[]` 로 명시 (블록 자체를 생략 금지). harness-next.sh 가 평가 직후 자동으로 이 블록들을 파싱하여 `.harness/gotchas/<target>.md` 와 `.harness/conventions/<scope>.md` 에 dedup append 한다.
+
+**왜 mandatory 인가**: 사용자 명시 — "Gen/Eval 이 발견한 패턴은 메뉴얼로 시키기 전에 동적으로 등록되어야 한다. 자동으로 패턴화되는 이슈는 등록하라." 한 번 발견된 실수가 다음 sprint 에서 반복되지 않게 하려면 평가자가 그 자리에서 등록하는 것이 유일한 closure.
+
+### 1) gotcha_candidates — 부정 가이드 (실수 패턴)
+
+평가 중 발견한 **반복 가능한 실수** (한 번이라도 동일 패턴이 다시 나올 위험이 있는 결함). 한 평가에서 0~N 개.
+
+검출 기준 (하나라도 해당하면 등록):
+- 같은 sprint 내 다른 feature 에서도 재발할 가능성이 있는 결함
+- generator 가 자주 빠뜨리는 케이스 (e.g. RSC↔CC 경계, schema 누락)
+- spec/contract 위반 패턴
+- AC 부분 통과 / Hard Gate 위반 사유
+
+```gotcha_candidates
+[
+  {
+    "target": "generator-frontend",
+    "rule_id": "rsc-cc-boundary-monitoring",
+    "title": "Server Component 에서 useState/useEffect 호출",
+    "wrong": "app/monitoring/page.tsx 에 'use client' 없이 hook 사용 → 빌드 통과해도 런타임에 깨짐",
+    "right": "client-side state 사용 시 파일 최상단에 'use client' 명시. 또는 server component 로 유지하면서 client 부분만 분리.",
+    "why": "Next.js App Router 의 RSC↔CC 경계는 정적 분석으로 100% 안 잡힘. F-209 에서 발견.",
+    "scope": "app/**/page.tsx, app/**/layout.tsx",
+    "source": "evaluator-functional:F-209"
+  }
+]
+```
+
+비어 있으면:
+```gotcha_candidates
+[]
+```
+
+### 2) convention_candidates — 긍정 가이드 (반복 가능한 best practice)
+
+평가 중 확립된 **반복 가능한 모범 사례** (다른 feature 에서도 같은 방식으로 적용해야 하는 룰). 한 평가에서 0~N 개.
+
+검출 기준:
+- 같은 sprint 의 다른 feature 가 모방해야 할 패턴
+- API 계약 / 폴더 구조 / 명명 규칙 관련 결정
+- 사용자가 "이렇게 해" 라고 한 한 번의 발언이 평가에서 일반화 가능한 경우
+
+```convention_candidates
+[
+  {
+    "scope": "generator-frontend",
+    "rule_id": "route-segment-files",
+    "title": "App Router 세그먼트 필수 파일 세트",
+    "rule": "모든 app/**/page.tsx 는 같은 폴더에 not-found.tsx, error.tsx, loading.tsx 를 함께 배치한다.",
+    "why": "Next.js 의 segment-level 에러/로딩 처리. 누락 시 default 흰 화면 노출. F-209 평가에서 표준화 결정.",
+    "source": "evaluator-functional:F-209"
+  }
+]
+```
+
+비어 있으면:
+```convention_candidates
+[]
+```
+
+**금지**: 두 블록 중 하나라도 누락된 채로 평가 종료 → On Complete protocol 위반. harness-next.sh 의 audit gate 에서 누락 감지 시 경고.

package/skills/evaluator-visual/SKILL.md

@@ -153,3 +153,13 @@ jq '.agent_status = "completed" | .completed_agents += ["planner"]'   .harness/p
 
 - **PASS** → Session Boundary Protocol On Complete (PASS) 실행
 - **FAIL** → Session Boundary Protocol On Fail 실행
+
+## ⚠ MANDATORY — 동적 Gotcha / Convention 등록
+
+evaluation-visual.md 의 끝에 **반드시 `gotcha_candidates` 와 `convention_candidates` fenced JSON 블록**을 작성한다 (비어 있으면 `[]`). harness-next.sh / Team Lead 가 자동 스캔하여 `.harness/gotchas/` `.harness/conventions/` 에 dedup append.
+
+**Visual eval 특화 검출 대상**:
+- 콘솔 에러/Hydration mismatch → `gotcha_candidates` (target=generator-frontend)
+- 디자인 토큰 불일치, 일관된 spacing/font 룰 → `convention_candidates` (scope=generator-frontend)
+
+상세 스키마 / 예시 / 필수 필드 → [공통 가이드 — dynamic-registration](../_shared/dynamic-registration.md)

package/skills/generator-backend/SKILL.md

@@ -119,3 +119,35 @@ api-contract.json 의 DTO 스키마는 해당 스택의 타입 표현(Pydantic /
 
 - `ref-docs` 가 placeholder 상태 → 본격 구현 전에 `bash init.sh refresh-ref be <stack>` 으로 채우기 권고
 - `scan-result.json.tech_stack_confidence == "unknown"` → 사용자에게 객관식 + 자유입력 fallback 로 스택 확인 요청
+
+## ⚠ MANDATORY — 동적 Gotcha / Convention 등록 (Generator 도 mandatory)
+
+작업 완료 시 `.harness/actions/gen-report-{FEATURE_ID}.md` 를 작성하고 끝에 **`gotcha_candidates` 와 `convention_candidates` fenced JSON 블록 두 개**를 포함한다 (비어 있으면 `[]`). harness-next.sh / Team Lead 가 자동 스캔하여 `.harness/gotchas/` `.harness/conventions/` 에 dedup append.
+
+**Generator 가 등록해야 하는 패턴** (자기 발견):
+- 한 번 시도했다가 깨졌던 접근, 자체 fix 한 코드 실수 → `gotcha_candidates` (target=generator-backend, source="generator-backend:F-XXX")
+- 작업 중 적용한 일관된 코드 구조/패턴 (다른 feature 가 모방해야 할) → `convention_candidates` (scope=generator-backend)
+
+`gen-report-{FEATURE_ID}.md` 최소 형식:
+```markdown
+# Generator-Backend Report — {FEATURE_ID}
+
+## 변경 파일
+- ...
+
+## 자체 게이트 결과
+- tsc: OK · eslint: 0 warn · jest: N/N
+
+## 발견 패턴
+(짧은 설명)
+
+```gotcha_candidates
+[]
+```
+
+```convention_candidates
+[]
+```
+```
+
+상세 스키마 → [공통 가이드 — dynamic-registration](../_shared/dynamic-registration.md)

package/skills/generator-frontend/SKILL.md

@@ -123,3 +123,13 @@ Team Mode 에서 Team Worker 가 호출할 때, 프롬프트에 `FEATURE_ID` 가
 
 - `ref-docs` 가 placeholder 상태(`generator: "init-ref-docs.sh (placeholder)"`) → 본격 구현 전에 Claude 세션에서 `bash init.sh refresh-ref fe <stack>` 후 프롬프트 실행으로 본문 채우기를 권고
 - `scan-result.json.tech_stack_confidence == "unknown"` → 사용자에게 객관식(감지 후보 top 5 + 자유입력 fallback)으로 스택 확인 요청
+
+## ⚠ MANDATORY — 동적 Gotcha / Convention 등록 (Generator 도 mandatory)
+
+작업 완료 시 `.harness/actions/gen-report-{FEATURE_ID}.md` 를 작성하고 끝에 **`gotcha_candidates` 와 `convention_candidates` fenced JSON 블록 두 개**를 포함한다 (비어 있으면 `[]`). harness-next.sh / Team Lead 가 자동 스캔하여 `.harness/gotchas/` `.harness/conventions/` 에 dedup append.
+
+**FE Generator 가 등록해야 하는 패턴** (자기 발견):
+- RSC↔CC 경계 위반, missing 'use client', not-found.tsx/error.tsx 누락, typed-routes 미스매치 → `gotcha_candidates` (target=generator-frontend)
+- 일관된 컴포넌트/훅/스타일 룰, 폴더 구조, shadcn 사용 패턴 → `convention_candidates` (scope=generator-frontend)
+
+상세 스키마 / `gen-report-{FEATURE_ID}.md` 형식 → [공통 가이드 — dynamic-registration](../_shared/dynamic-registration.md)