@walwal-harness/cli 5.4.1 → 5.5.1

package/assets/templates/HARNESS.md

@@ -1,4 +1,4 @@
-# 6-Agent Production Harness — 사용 가이드
+# 7-Agent Production Harness — 사용 가이드
 
 > Anthropic 블로그 "Harness Design for Long-Running Application Development" 기반
 > Solo: 20min/$9 (broken) → Harness: 6hr/$200 (fully functional)
@@ -42,16 +42,37 @@ CONVENTIONS.md                    # 프로젝트 컨벤션 (사용자 작성,
  FULLSTACK  FE-ONLY   BE-ONLY
 ```
 
+### Evaluator Chain (공통)
+
+Generator 이후는 **3-Evaluator 직렬 체인 + 조기 종료**:
+
+```
+Generator
+  → Eval-Code-Quality  (정적 · 저비용 · 브라우저 없음)
+  → Eval-Functional    (동작 · 중비용 · Playwright/curl)
+  → Eval-Visual        (렌더 · 고비용 · 스크린샷)
+  → Archive
+```
+
+앞단 FAIL 시 뒤 평가자는 실행하지 않고 즉시 Generator 재작업으로 리라우팅.
+구조가 깨진 코드에 동작/렌더 테스트를 낭비하지 않기 위함.
+
+| 평가자 | 관심사 | 도구 |
+|--------|--------|------|
+| evaluator-code-quality | 유지보수성·레이어·타입 안정성·테스트 품질 (BE/FE/libs 공통) | Read/Grep + tsc/eslint |
+| evaluator-functional   | 엔드포인트·E2E 사용자 플로우·API 계약 준수                  | Playwright(browser_*) 또는 curl(api-only) |
+| evaluator-visual       | 레이아웃·반응형·접근성·AI슬롭                               | Playwright(screenshot/resize/snapshot) |
+
 ### FULLSTACK — 신규 PRD 기반 풀스택
 
 ```
-Planner → Gen-BE → Gen-FE → Eval-Func → Eval-Visual → Archive
+Planner → Gen-BE → Gen-FE → Eval-Code-Quality → Eval-Func → Eval-Visual → Archive
 ```
 
 ### FE-ONLY — 기존 API + 프론트엔드 연동
 
 ```
-Planner(light) → Gen-FE → Eval-Func → Eval-Visual → Archive
+Planner(light) → Gen-FE → Eval-Code-Quality → Eval-Func → Eval-Visual → Archive
     │
     └─ OpenAPI spec → api-contract.json 변환
        Gen-BE SKIP (외부 서버 사용)
@@ -60,7 +81,7 @@ Planner(light) → Gen-FE → Eval-Func → Eval-Visual → Archive
 ### BE-ONLY — 기존 서버 + 백엔드 기능 추가
 
 ```
-Planner → Gen-BE → Eval-Func(API-only) → Archive
+Planner → Gen-BE → Eval-Code-Quality → Eval-Func(API-only) → Archive
     │
     └─ 기존 코드 분석 후 확장 설계
        Gen-FE SKIP, Eval-Visual SKIP
@@ -70,8 +91,9 @@ Planner → Gen-BE → Eval-Func(API-only) → Archive
 ### 공통 — 실패 시 루프
 
 ```
-Eval-Func FAIL → failure_location에 따라 Gen-BE 또는 Gen-FE 재작업 (max 5회)
-Eval-Visual FAIL → Gen-FE 재작업 (max 5회)
+Eval-Code-Quality FAIL → failure.location 에 따라 Gen-BE 또는 Gen-FE 재작업 (뒤 평가자 실행 없음)
+Eval-Func FAIL         → 동일 규칙으로 재작업
+Eval-Visual FAIL       → Gen-FE 재작업
 3회 실패 → Planner 에스컬레이션 (scope 축소/접근 변경)
 5회 초과 → 사용자 개입 요청
 ```
@@ -282,6 +304,16 @@ jq . .harness/progress.json         # 현재 상태 확인
 | FAIL 기준 | 2.79 이하 (예외 없음) |
 | Evidence 없는 항목 | Score = 0으로 강제 재계산 |
 
+### Evaluator-Code-Quality 채점 항목 (C1-C5)
+
+| # | Criterion | Weight |
+|---|-----------|--------|
+| C1 | Layer & Boundary (IA-MAP/MSA/FE VM 경계) | 25% |
+| C2 | Readability & Complexity | 15% |
+| C3 | Reuse & DRY | 20% |
+| C4 | Type Safety & Error Handling | 25% |
+| C5 | Test Quality | 15% |
+
 ### Evaluator-Functional 채점 항목 (R1-R5)
 
 | # | Criterion | Weight |

package/assets/templates/config.json

@@ -1,8 +1,8 @@
 {
   "harness": {
-    "name": "6-Agent Production Harness",
-    "version": "5.0.0",
-    "description": "Solo/Team 통합 하네스 — Dispatcher + NestJS MSA + React/Next.js + Playwright",
+    "name": "7-Agent Production Harness",
+    "version": "5.5.0",
+    "description": "Solo/Team 통합 하네스 — Dispatcher + 3-Evaluator Chain (Code-Quality → Functional → Visual) + NestJS MSA + React/Next.js + Playwright",
     "source": "https://www.anthropic.com/engineering/harness-design-long-running-apps"
   },
   "agents": {
@@ -73,6 +73,36 @@
       "thinking_mode": null,
       "model_rationale": "코드 생성은 Sonnet이 비용 대비 효율적. 계획은 Planner가 이미 완료."
     },
+    "evaluator-code-quality": {
+      "role": "코드 자체의 유지보수성/아키텍처/Best Practice 검사 (BE/FE/libs 공통, 브라우저 없음)",
+      "skill": "harness-evaluator-code-quality",
+      "tools": ["Read", "Grep", "Glob", "Bash(tsc,eslint,biome,lint 스크립트 한정)"],
+      "inputs": ["actions/sprint-contract.md", "actions/feature-list.json", "actions/api-contract.json"],
+      "outputs": ["actions/evaluation-code-quality.md"],
+      "model": "opus",
+      "thinking_mode": "ultrathink",
+      "thinking_mode_description": "시니어 리뷰어 관점. 변경 파일 전수 정적 분석 + C1-C5 축 적대적 채점.",
+      "adversarial_rules": {
+        "comment": "Code-Quality Evaluator 적대적 행동 규칙 — rubber-stamping 금지",
+        "rules": [
+          "브라우저 없이 코드만으로 판정. '동작하니 PASS' 금지.",
+          "변경 파일(git diff)은 전수 검사. '시간 제약' 핑계 금지.",
+          "모든 Score 주장은 파일:라인 evidence 동반. Evidence 없는 Score = 0.",
+          "toolchain(tsc/eslint) 에러 1건 이상이면 나머지 축 채점 전 즉시 FAIL.",
+          "api-contract.json ↔ 실제 DTO/시그니처 불일치 1건 이상 = FAIL.",
+          "레이어 역방향 의존 / MSA 직접 DB 접근 / FE view→fetch 직결 1건 이상 = C1 Score 0.",
+          "unhandled promise 1건 이상 또는 비타당한 any 3건 이상 = C4 Score 0.",
+          "PASS를 주기 전에 자문하라: '내가 이 코드를 머지 승인할 수 있는가?' NO이면 FAIL.",
+          "반복 페널티: 같은 축에서 이전 스프린트 대비 악화 시 Score 최대 1."
+        ],
+        "forbidden": [
+          "'동작은 Functional 에서 확인됐으니 OK' 식의 책임 전가",
+          "'관용적 any', '사소한 중복' 같은 자기설득",
+          "'제안사항만 남기고 Pass' — 필수 개선은 FAIL",
+          "파일 수정/커밋 (이 평가자는 읽기 전용)"
+        ]
+      }
+    },
     "evaluator-functional": {
       "role": "Playwright로 E2E 기능 검증, API 응답/DB 상태 확인",
       "skill": "harness-evaluator-functional",
@@ -135,13 +165,26 @@
     }
   },
   "flow": {
-    "sequence": ["dispatcher", "planner", "generator-backend", "generator-frontend", "evaluator-functional", "evaluator-visual"],
+    "sequence": ["dispatcher", "planner", "generator-backend", "generator-frontend", "evaluator-code-quality", "evaluator-functional", "evaluator-visual"],
+    "evaluator_chain": {
+      "comment": "Generator 완료 후 실행되는 평가자 체인. 직렬 실행 + 조기 종료 — 앞단 FAIL 시 이후 평가자는 생략하고 Generator 로 리라우팅. 모두 PASS 여야 다음 스프린트로 이동.",
+      "execution": "serial_with_early_exit",
+      "order_rationale": "code-quality(정적, 저비용) → functional(동작, 중비용) → visual(렌더, 고비용). 구조가 깨진 코드에 동작 테스트를 낭비하지 않기 위함.",
+      "on_any_fail": "reroute_to_generator",
+      "on_all_pass": "advance_sprint"
+    },
     "pipeline_selection": {
       "comment": "Dispatcher가 pipeline.json으로 활성 에이전트를 결정.",
       "pipelines": {
-        "FULLSTACK": ["planner", "generator-backend", "generator-frontend", "evaluator-functional", "evaluator-visual"],
-        "FE-ONLY": ["planner:light", "generator-frontend", "evaluator-functional", "evaluator-visual"],
-        "BE-ONLY": ["planner", "generator-backend", "evaluator-functional:api-only"]
+        "FULLSTACK": ["planner", "generator-backend", "generator-frontend", "evaluator-code-quality", "evaluator-functional", "evaluator-visual"],
+        "FE-ONLY": ["planner:light", "generator-frontend", "evaluator-code-quality", "evaluator-functional", "evaluator-visual"],
+        "BE-ONLY": ["planner", "generator-backend", "evaluator-code-quality", "evaluator-functional:api-only"]
+      },
+      "evaluator_chains": {
+        "comment": "파이프라인별 평가자 체인. Dispatcher가 pipeline.json.evaluator_chain 으로 기록.",
+        "FULLSTACK": ["evaluator-code-quality", "evaluator-functional", "evaluator-visual"],
+        "FE-ONLY": ["evaluator-code-quality", "evaluator-functional", "evaluator-visual"],
+        "BE-ONLY": ["evaluator-code-quality", "evaluator-functional"]
       }
     },
     "sprint_execution": {
@@ -198,7 +241,7 @@
     },
     "cross_validation": {
       "enabled": true,
-      "comment": "evaluator-functional과 evaluator-visual이 서로의 결과를 참조하여 불일치를 감지. evaluation-*.md의 Cross-Validation Data JSON 블록을 기계적으로 파싱."
+      "comment": "evaluator-code-quality / evaluator-functional / evaluator-visual 세 평가자의 결과를 상호 참조하여 불일치를 감지. evaluation-*.md의 Cross-Validation Data JSON 블록을 기계적으로 파싱."
     },
     "acceptance_criteria_schema": {
       "comment": "Planner가 feature-list.json에 기능 정의 시 반드시 작성해야 하는 실행 가능한 검증 조건 스키마. Evaluator는 이 조건을 기계적으로 실행한다.",
@@ -267,6 +310,9 @@
         "api-contract.json": "draft",
         "feature-list.json": "draft"
       },
+      "evaluator-code-quality": {
+        "sprint-contract.md": "draft"
+      },
       "evaluator-functional": {
         "sprint-contract.md": "draft"
       },

package/gotchas/evaluator-code-quality.md

@@ -0,0 +1,21 @@
+---
+docmeta:
+  id: evaluator-code-quality-gotchas
+  title: Gotchas — Evaluator-Code-Quality
+  type: input
+  createdAt: 2026-04-22T00:00:00Z
+  updatedAt: 2026-04-22T00:00:00Z
+  source:
+    producer: user
+    skillId: harness-dispatcher
+  tags:
+    - gotchas
+    - evaluator
+    - code-quality
+---
+
+# Gotchas — Evaluator-Code-Quality
+
+> Dispatcher가 관리. Evaluator-Code-Quality는 세션 시작 시 이 파일을 읽고 같은 실수를 반복하지 않습니다.
+
+<!-- 항목이 추가되면 아래에 기록됩니다 -->

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@walwal-harness/cli",
-  "version": "5.4.1",
-  "description": "Production harness for AI agent engineering — Solo/Team mode, Planner, Generator(BE/FE), Evaluator(Func/Visual), optional Brainstormer. Supports React, Next.js, and Flutter FE stacks.",
+  "version": "5.5.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-dashboard.sh

@@ -271,7 +271,7 @@ render_team_features() {
     ($q[0].queue.in_progress // {}) as $prog |
     .features[] |
     .id as $fid |
-    (.name // .description // "?" | if length > 18 then .[0:16] + ".." else . end) as $fname |
+    (.name // .title // .description // "?" | if length > 18 then .[0:16] + ".." else . end) as $fname |
     (if ($fid | IN($passed[])) then "P"
      elif $prog[$fid] then "I|\($prog[$fid].team)|\($prog[$fid].phase)"
      elif ($fid | IN($failed[])) then "F"

package/scripts/harness-next.sh

@@ -442,7 +442,14 @@ if [ "$next_agent" != "null" ] && [ "$next_agent" != "archive" ] && [ "$agent_st
       ;;
   esac
 
-  # ── Cross-Validation ──
+  # ── Cross-Validation (chain: code-quality → functional → visual) ──
+  local cross_validation_from_code_quality="null"
+  if [ "$next_agent" = "evaluator-functional" ] || [ "$next_agent" = "evaluator-visual" ]; then
+    local cq_eval="$PROJECT_ROOT/.harness/actions/evaluation-code-quality.md"
+    if [ -f "$cq_eval" ]; then
+      cross_validation_from_code_quality=$(sed -n '/```json/,/```/p' "$cq_eval" | tail -n +2 | head -n -1 | jq 'select(.evaluator == "code-quality" or .cross_validation_from_code_quality)' 2>/dev/null || echo "null")
+    fi
+  fi
   if [ "$next_agent" = "evaluator-visual" ]; then
     local func_eval="$PROJECT_ROOT/.harness/actions/evaluation-functional.md"
     if [ -f "$func_eval" ]; then
@@ -466,6 +473,7 @@ if [ "$next_agent" != "null" ] && [ "$next_agent" != "archive" ] && [ "$agent_st
     --argjson regression "$regression_source" \
     --argjson eval_config "$eval_config" \
     --argjson cross_val "$cross_validation_data" \
+    --argjson cross_val_cq "$cross_validation_from_code_quality" \
     --arg timestamp "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
     '{
       from: $from,
@@ -482,6 +490,7 @@ if [ "$next_agent" != "null" ] && [ "$next_agent" != "archive" ] && [ "$agent_st
       regression: $regression,
       eval_config: $eval_config,
       cross_validation_from_functional: $cross_val,
+      cross_validation_from_code_quality: $cross_val_cq,
       warnings: [],
       timestamp: $timestamp
     }' > "$HANDOFF"

package/scripts/harness-statusline.sh

@@ -67,6 +67,7 @@ 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-code-quality")) | length > 0) and
       (map(select(. == "evaluator-functional")) | length > 0) and
       (map(select(. == "evaluator-visual")) | length > 0)
     )

package/scripts/lib/harness-guardrail.sh

@@ -39,6 +39,10 @@ get_allowed_paths() {
       echo "tsconfig"
       echo "pubspec"
       ;;
+    evaluator-code-quality)
+      echo ".harness/actions/evaluation-code-quality.md"
+      echo ".harness/progress.json"
+      ;;
     evaluator-functional|evaluator-functional-flutter)
       echo ".harness/actions/evaluation-functional.md"
       echo ".harness/progress.json"

package/scripts/lib/harness-render-progress.sh

@@ -111,7 +111,7 @@ render_progress() {
       while [ $i -lt "$total_features" ]; do
         local fid fname passes be_pass fe_pass eval_func_pass eval_visual_pass
         fid=$(jq -r ".features[$i].id // \"F-$((i+1))\"" "$FEATURES")
-        fname=$(jq -r ".features[$i].name // .features[$i].description // \"Feature $((i+1))\"" "$FEATURES")
+        fname=$(jq -r ".features[$i].name // .features[$i].title // .features[$i].description // \"Feature $((i+1))\"" "$FEATURES")
         passes=$(jq -r ".features[$i].passes // [] | .[]" "$FEATURES" 2>/dev/null)
 
         # Truncate name to 20 chars
@@ -120,23 +120,29 @@ render_progress() {
         fi
 
         # Check passes
-        be_pass="○"; fe_pass="○"; eval_func_pass="○"; eval_visual_pass="○"
+        be_pass="○"; fe_pass="○"; eval_cq_pass="○"; eval_func_pass="○"; eval_visual_pass="○"
         local eval_done=false
 
         while IFS= read -r p; do
           case "$p" in
-            generator-backend)    be_pass="✓" ;;
-            generator-frontend)   fe_pass="✓" ;;
-            evaluator-functional) eval_func_pass="✓" ;;
-            evaluator-visual)     eval_visual_pass="✓" ;;
+            generator-backend)       be_pass="✓" ;;
+            generator-frontend)      fe_pass="✓" ;;
+            evaluator-code-quality)  eval_cq_pass="✓" ;;
+            evaluator-functional)    eval_func_pass="✓" ;;
+            evaluator-visual)        eval_visual_pass="✓" ;;
           esac
         done <<< "$passes"
 
-        # Eval column: both must pass
+        # Eval column: chain 내 존재하는 평가자 모두 PASS 여야 ✓
         local eval_pass="○"
-        if [ "$eval_func_pass" = "✓" ] && [ "$eval_visual_pass" = "✓" ]; then
+        local eval_passed_count=0
+        local eval_total=3
+        [ "$eval_cq_pass" = "✓" ]      && eval_passed_count=$((eval_passed_count + 1))
+        [ "$eval_func_pass" = "✓" ]    && eval_passed_count=$((eval_passed_count + 1))
+        [ "$eval_visual_pass" = "✓" ]  && eval_passed_count=$((eval_passed_count + 1))
+        if [ "$eval_passed_count" -eq "$eval_total" ]; then
           eval_pass="✓"
-        elif [ "$eval_func_pass" = "✓" ] || [ "$eval_visual_pass" = "✓" ]; then
+        elif [ "$eval_passed_count" -gt 0 ]; then
           eval_pass="◐"
         fi
 
@@ -204,22 +210,19 @@ render_progress() {
             generator-frontend)
               if [ "$show_fe" = true ]; then done_steps=$((done_steps + 1)); fi
               ;;
-            evaluator-functional|evaluator-visual)
-              # Each eval counts as 0.5 of the eval step
-              # We'll handle this by checking both at the end
+            evaluator-code-quality|evaluator-functional|evaluator-visual)
+              # Chain 내 평가자. 아래에서 통합 집계.
               ;;
           esac
         done <<< "$passes"
 
-        # Check eval completion
-        local ef ev
+        # Check eval completion — 체인상의 3개 평가자 모두 통과 시에만 1 step 인정
+        local ecq ef ev
+        ecq=$(jq -r ".features[$i].passes // [] | map(select(. == \"evaluator-code-quality\")) | length" "$FEATURES" 2>/dev/null)
         ef=$(jq -r ".features[$i].passes // [] | map(select(. == \"evaluator-functional\")) | length" "$FEATURES" 2>/dev/null)
         ev=$(jq -r ".features[$i].passes // [] | map(select(. == \"evaluator-visual\")) | length" "$FEATURES" 2>/dev/null)
-        if [ "${ef:-0}" -gt 0 ] && [ "${ev:-0}" -gt 0 ]; then
+        if [ "${ecq:-0}" -gt 0 ] && [ "${ef:-0}" -gt 0 ] && [ "${ev:-0}" -gt 0 ]; then
           done_steps=$((done_steps + 1))
-        elif [ "${ef:-0}" -gt 0 ] || [ "${ev:-0}" -gt 0 ]; then
-          # partial eval — don't count
-          :
         fi
 
         i=$((i + 1))

package/skills/dispatcher/SKILL.md

@@ -25,22 +25,8 @@ disable-model-invocation: false
    - `pipeline` → 선택된 파이프라인 (FULLSTACK/FE-ONLY/BE-ONLY)
    - `sprint.number` → `1`, `sprint.status` → `"in_progress"` (신규 파이프라인인 경우에만)
 2. `.harness/progress.log`에 요약 한 줄 추가
-3. **모드 감지**: `.harness/progress.json`의 `mode` 필드 확인
-   - **`"team"`**: Team Mode 활성. 별도 안내 없이 즉시 STOP.
-     출력 (아래 3줄을 그대로 사용):
-     ```
-     ✓ Dispatcher 완료 — pipeline.json 생성됨 (next_agent=<값>).
-     → 별도 tmux 창의 Team Worker들이 이 파일을 감지해 자동으로 다음 에이전트를 실행합니다. 사용자 입력은 필요 없습니다.
-     → 진행 상황은 tmux Dashboard/Team 패널에서 확인하세요. 중단하려면 `bash scripts/harness-tmux.sh --kill`.
-     ```
-   - **`"solo"` / `"paused"`**: Solo Mode. 자동 실행되는 것이 아무것도 없음 — 사용자 입력 대기.
-     출력 (아래 2줄을 그대로 사용):
-     ```
-     ✓ Dispatcher 완료 — pipeline.json 생성됨 (next_agent=<값>). 자동 실행은 시작되지 않았습니다.
-     → 다음 에이전트를 돌리려면 `/harness-solo` 를 입력하거나, 그냥 후속 지시를 프롬프트로 주세요.
-     ```
-4. **STOP. 다음 에이전트를 직접 호출하지 않는다.**
-   - Team 모드에서는 `/harness-team 실행하시겠습니까?` 같은 **질문을 하지 않는다**. Teams는 이미 실행 중이거나 사용자가 별도로 시작한다.
+3. **STOP. 다음 에이전트를 직접 호출하지 않는다.**
+4. 출력: `"✓ Dispatcher 완료. bash scripts/harness-next.sh 실행하여 다음 단계 확인."`
 
 ## Auto-Routing (UserPromptSubmit Hook)
 
@@ -120,13 +106,34 @@ AGENTS.md 비하네스  → 기존 백업 + 리빌드
 
 `.harness/actions/pipeline.json` 생성 → 사용자 확인 → Session Boundary Protocol On Complete 실행
 
+### evaluator_chain 필드 (모든 파이프라인 필수)
+
+`pipeline.json` 에 **`evaluator_chain`** 배열을 기록한다. `config.json.flow.pipeline_selection.evaluator_chains.<pipeline>` 의 값을 복사:
+
+- FULLSTACK / FE-ONLY: `["evaluator-code-quality", "evaluator-functional", "evaluator-visual"]`
+- BE-ONLY: `["evaluator-code-quality", "evaluator-functional"]` (functional 은 api-only 모드)
+
+Flutter 치환 규칙은 chain 배열의 각 원소에도 동일 적용. `fe_stack == "flutter"` + `fe_target in (mobile, desktop)` 이면 `evaluator-visual` 을 chain 에서 제거하고 `evaluator-functional` → `evaluator-functional-flutter` 로 치환한다. `evaluator-code-quality` 는 스택/타겟 무관 공통.
+
+### Evaluator 체인 라우팅 규칙
+
+Generator 완료 후 `next_agent` 는 chain[0] (항상 `evaluator-code-quality`).
+
+각 평가자의 On Complete:
+- **PASS**: chain 상 다음 평가자로 `next_agent` 설정. 마지막 평가자면 `archive`.
+- **FAIL**: chain 나머지 **건너뛰고** `failure.retry_target` (해당 결함 위치의 Generator) 로 리라우팅.
+
+Gotcha retry 시에도 체인 시작점은 chain[0] 부터 재실행.
+
 ### fe_stack 필드 (FE 파이프라인에서 필수)
 
-FE-ONLY 또는 FULLSTACK 선택 시, `pipeline.json` 에 **`fe_stack`** 필드를 포함해야 한다:
+FE-ONLY 또는 FULLSTACK 선택 시, `pipeline.json`에 **`fe_stack`** 필드를 포함해야 한다:
 
-- `scan-result.json.tech_stack.fe_stack` (또는 `tech_stack.frontend`) 값을 기본으로 사용
-- 값이 없거나 불명확하면 Planner 가 확정하도록 위임 (Dispatcher 는 `"unknown"` 기록 + `notes` 에 메모)
-- v5.2 이후: **에이전트 분기 없음** — 동일한 `generator-frontend` / `evaluator-functional` 에이전트가 `.harness/ref/fe-<fe_stack>.md` 를 로드해 스택 적응적으로 동작
+- `scan-result.json.tech_stack.fe_stack` 값을 기본으로 사용 (`react` | `flutter`)
+- 값이 없거나 불명확하면 Planner가 확정하도록 위임 (Dispatcher는 `"unknown"` 기록 + `notes` 에 메모)
+- Flutter 선택 시 `agents_active`/`agents_skipped`에 치환된 에이전트명을 기록
+  - active: `generator-frontend-flutter`, `evaluator-functional-flutter`
+  - skipped: `generator-frontend`, `evaluator-functional`, `evaluator-visual`
 
 ## 6. Brainstormer Routing Decision
 
@@ -181,7 +188,7 @@ Planner 를 호출해야 한다고 판단되면, **사용자에게 단 하나의
 | 상황 | next_agent |
 |------|-----------|
 | "Eval, X 다시 검증해" | `evaluator-functional` (또는 `evaluator-visual`) |
-| "Generator-FE, Y 버그 고쳐" | `generator-frontend` |
+| "Generator-FE, Y 버그 고쳐" | `generator-frontend` (또는 Flutter 변형) |
 | "Generator-BE, API 재생성해" | `generator-backend` |
 | Eval FAIL → retry | `failure.retry_target` |
 | Gotcha 수정 | `failure.retry_target` 또는 현재 에이전트 |
@@ -199,48 +206,14 @@ Planner 를 호출해야 한다고 판단되면, **사용자에게 단 하나의
 이 경우 기존 `.harness/actions/brainstorm-spec.md` 는 Brainstormer 의 On Start 에서
 `.harness/archive/brainstorm-spec-<timestamp>.md` 로 백업된다.
 
-## 7. Handoff 라우팅 (v5.2 — 스택 치환 없음)
-
-v5.2 이후 에이전트 치환은 사용하지 않는다. Dispatcher 가 `next_agent` 를 세팅할 때 `pipeline.json.fe_stack` 은 **참고용 메타데이터**로만 기록되고, 실제 스택별 행동은 에이전트가 자기 On Start 에서 `.harness/ref/<role>-<stack>.md` 를 로드해 결정한다.
-
-| 에이전트 | 스택 적응 메커니즘 |
-|---------|------------------|
-| `generator-frontend` | On Start 에서 `.harness/ref/fe-<stack>.md` 로드 |
-| `generator-backend` | On Start 에서 `.harness/ref/be-<stack>.md` 로드 |
-| `evaluator-functional` | `ref.validation.pre_eval_gate` / `functional_tests` / `anti_pattern_rules` 실행 |
-| `evaluator-visual` | `ref.validation.visual.enabled == false` 면 MANUAL_REQUIRED 로 skip |
-
-## 8. Auto Gotcha Registration (v5.2)
-
-evaluator-functional / evaluator-visual 이 안티패턴을 발견하면 Dispatcher 경유로 자동 gotcha 파일에 등록한다. 이 섹션은 Dispatcher 가 등록 이벤트를 받았을 때의 행동을 정의한다.
-
-### 8.1 수신 이벤트 페이로드
-
-`api-contract.json.contracts["gotcha_register_interface"]` 참조. 필수 필드:
-- `agent` (예: `"generator-frontend"`)
-- `stack` (예: `"swift"`)
-- `rule_id`, `severity`, `occurrences[] (file/line/snippet)`, `source_feature`
-
-### 8.2 대상 파일 결정
-
-`.harness/gotchas/<agent>-<stack>.md` (없으면 생성). 스택 특정 규칙이 아닌 공통 규칙은 `<agent>.md` 로 라우팅 (gotcha-flow.md 의 "라우팅 규칙" 참조).
-
-### 8.3 등록 절차
-
-```
-1. 대상 파일 열기 (없으면 표준 헤더로 생성)
-2. 기존 항목 중 같은 rule_id 검색:
-   - 있음 → Occurrences +1, Last seen 업데이트, snippet 최신으로 교체
-   - 없음 → 다음 G-NNN 번호로 새 항목 추가
-3. progress.log 에 `"auto_gotcha_registered"` 이벤트 기록
-4. evaluation-*.md 에 "Registered gotchas: <G-IDs>" 요약 기록
-```
-
-항목 포맷은 gotcha-flow.md 의 "Gotcha 항목 형식" 섹션과 동일.
+## 7. Handoff 라우팅 (fe_stack 반영)
 
-### 8.4 멱등성 / 중복 방지
+Dispatcher가 `next_agent` 를 세팅할 때 pipeline.json.fe_stack 을 참조해 치환:
 
-- 동일 feature 의 동일 rule_id 는 한 번의 평가 안에서 최대 1회만 Occurrences 증가
-- Retry 시에는 이전 Occurrences 유지 (재평가이므로 중복 카운팅 금지)
+| 원본 next_agent | fe_stack=react | fe_stack=flutter |
+|-----------------|----------------|------------------|
+| generator-frontend | generator-frontend | generator-frontend-flutter |
+| evaluator-functional (FE 단계) | evaluator-functional | evaluator-functional-flutter |
+| evaluator-visual | evaluator-visual | (skip → 다음 단계로 이동) |
 
-**Brainstormer 는 스택 치환 대상이 아니다** — 언어/스택 무관 공통 에이전트.
+**Brainstormer 는 fe_stack 치환 대상이 아니다** — 언어/스택 무관 공통 에이전트.

package/skills/dispatcher/references/pipeline-definitions.md

@@ -58,6 +58,23 @@ if pipeline.json.fe_stack == "flutter":
         "evaluator-visual"     → __skip__
 ```
 
+## Evaluator Chain (공통)
+
+모든 파이프라인의 Generator 이후 단계는 **평가자 체인**으로 처리한다. 직렬 실행 + 조기 종료:
+
+```
+Generator → evaluator-code-quality → evaluator-functional → evaluator-visual → archive
+                    │                        │                      │
+                    └─ FAIL ─ reroute ────────┴──────────────────────┘
+                              → Generator (failure.retry_target)
+```
+
+- **code-quality** (정적, 저비용, 브라우저 없음): BE/FE/libs 공통 코드 품질
+- **functional** (동작, 중비용): API·E2E 행동 검증
+- **visual** (렌더, 고비용): 레이아웃/접근성
+
+앞단 FAIL 시 뒷단은 실행하지 않는다. 구조가 깨진 코드에 동작 테스트 낭비 방지.
+
 ## FE-ONLY
 
 ```yaml
@@ -67,15 +84,20 @@ agents:
       skip: MSA 서비스 설계, BE 기능 목록
       do: OpenAPI → api-contract.json 변환, FE 컴포넌트 설계, feature-list (layer: frontend만), fe_stack 확정
   - generator-frontend OR generator-frontend-flutter  # fe_stack에 따라
+  - evaluator-code-quality                             # 공통 — 브라우저 없음
   - evaluator-functional OR evaluator-functional-flutter
-  - evaluator-visual  # fe_stack == "flutter" 이면 SKIP
+  - evaluator-visual  # fe_stack == "flutter" + fe_target in (mobile,desktop) 이면 SKIP
+evaluator_chain:
+  - evaluator-code-quality
+  - evaluator-functional
+  - evaluator-visual
 skip:
   - generator-backend
 notes:
   - api-contract.json은 OpenAPI에서 파생 (Planner가 변환)
   - Eval-Func(React)의 API Health Check는 외부 서버 대상
   - AGENTS.md IA-MAP에 BE 경로 없음 (외부 서버)
-  - fe_stack=flutter 인 경우 evaluator-visual 생략
+  - fe_stack=flutter (mobile/desktop) 인 경우 evaluator-visual 생략
 ```
 
 ## BE-ONLY
@@ -87,15 +109,20 @@ agents:
       skip: FE 컴포넌트 설계, 비주얼 요구사항
       do: 기존 코드 분석, 신규 API 설계, api-contract.json 확장
   - generator-backend
+  - evaluator-code-quality                  # 공통
   - evaluator-functional:
       mode: api-only
       skip: browser 테스트
       do: curl/httpie로 API 엔드포인트 직접 검증
+evaluator_chain:
+  - evaluator-code-quality
+  - evaluator-functional
 skip:
   - generator-frontend
   - evaluator-visual
 notes:
   - Eval-Func는 Playwright 대신 CLI 기반 API 테스트
+  - Code-Quality 는 BE 코드의 레이어/DI/DTO/에러 전파/테스트 품질 감사
 ```
 
 ## FULLSTACK
@@ -106,6 +133,11 @@ agents:
   - planner (full)
   - generator-backend
   - generator-frontend
+  - evaluator-code-quality
+  - evaluator-functional
+  - evaluator-visual
+evaluator_chain:
+  - evaluator-code-quality
   - evaluator-functional
   - evaluator-visual
 skip: none

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

@@ -0,0 +1,161 @@
+---
+name: harness-evaluator-code-quality
+description: "하네스 Code-Quality Evaluator. 브라우저 없이 코드 자체를 읽어 유지보수성·모범사례 준수·아키텍처 건전성을 검사한다. BE/FE/lib 전 영역 적용. C1-C5 축으로 적대적 채점. 기준 미달 = FAIL."
+disable-model-invocation: true
+---
+
+# Evaluator-Code-Quality — Static Code Audit (No Browser)
+
+> Functional/Visual 평가자보다 **먼저** 실행된다. 코드가 구조적으로 망가졌으면
+> 동작 테스트는 의미 없다. 이 게이트에서 FAIL 이면 Functional/Visual 은 아예 시작도 하지 않는다.
+
+## Session Boundary Protocol
+
+### On Start
+1. `.harness/progress.json` 읽기 — `next_agent`가 `"evaluator-code-quality"`인지 확인
+2. progress.json 업데이트: `current_agent` → `"evaluator-code-quality"`, `agent_status` → `"running"`, `updated_at` 갱신
+
+### On Complete (PASS)
+1. progress.json 업데이트:
+   - `agent_status` → `"completed"`
+   - `completed_agents`에 `"evaluator-code-quality"` 추가
+   - `next_agent` → **evaluator chain의 다음 노드** (일반적으로 `"evaluator-functional"`; chain 이 `evaluator-code-quality` 단독이면 `"archive"`)
+   - `failure` 필드 초기화
+2. `feature-list.json`의 통과 feature `passes`에 `"evaluator-code-quality"` 추가
+3. `.harness/progress.log`에 PASS 요약 추가
+4. **STOP. 다음 에이전트를 직접 호출하지 않는다.**
+5. 출력: `"✓ Evaluator-Code-Quality PASS. bash scripts/harness-next.sh 실행하여 다음 단계 확인."`
+
+### On Fail
+1. progress.json 업데이트:
+   - `agent_status` → `"failed"`
+   - `failure.agent` → `"evaluator-code-quality"`
+   - `failure.location` → `"backend"` / `"frontend"` / `"shared"` (결함 위치; 혼재 시 주 결함 위치)
+   - `failure.message` → 실패 요약 (1줄)
+   - `failure.retry_target` → 결함 위치에 대응하는 Generator (`"generator-backend"` 또는 `"generator-frontend"`)
+   - `next_agent` → `failure.retry_target`
+   - `sprint.retry_count` 증가
+2. `sprint.retry_count >= 10`이면 `agent_status` → `"blocked"`, 사용자 개입 요청
+3. `.harness/progress.log`에 FAIL 요약 추가
+4. **STOP.**
+5. 출력: `"✖ Evaluator-Code-Quality FAIL. bash scripts/harness-next.sh 실행하여 재작업 대상 확인."`
+
+## Critical Mindset
+
+- **회의적 시니어 리뷰어.** Generator가 "깔끔하다"고 주장해도 직접 읽는다.
+- 실행·렌더링 없이 판정. 브라우저/서버 기동 금지 (불필요한 비용).
+- 파일 수정 금지. 오직 읽기 + 정적 분석기 실행.
+- "동작하니 통과"는 Functional 의 일. 여기서는 **동작해도 구조가 나쁘면 FAIL**.
+- Best Practice 위반을 "사소하다"고 자기설득 금지.
+
+## Scope — "시각과 무관한 코드 품질 전부"
+
+이 평가자는 **도메인(BE/FE)을 구분하지 않는다.**
+
+- Backend: controller/service/repo 레이어링, DI, DTO, 에러 전파, 트랜잭션 경계, MSA 메시지 패턴
+- Frontend 비주얼-외 로직: 상태관리(store/VM/hooks), 데이터 페칭, 라우팅, API 어댑터, 유틸
+- Shared libs: 공유 DTO/유틸/타입 정의, 순환 의존, 과도한 export
+
+**제외 영역** (다른 평가자 담당):
+- 렌더링 결과, 레이아웃, 스크린샷 → Evaluator-Visual
+- 엔드포인트 응답값·사용자 플로우 동작 → Evaluator-Functional
+
+## Startup
+
+1. `AGENTS.md` 읽기 — IA-MAP (레이어 경계)
+2. `CONVENTIONS.md` 읽기 — 프로젝트 컨벤션 (있을 때만)
+3. `.harness/gotchas/evaluator-code-quality.md` 읽기 — **과거 실수 반복 금지**
+4. `.harness/memory.md` 읽기 — **프로젝트 공유 학습 규칙 적용**
+5. `actions/sprint-contract.md` — 이번 스프린트 변경 범위
+6. `actions/feature-list.json` — 기능 정의
+7. `actions/api-contract.json` — DTO 형태 (계약 vs 구현 일치 확인용)
+8. `.harness/progress.json`
+
+## Evaluation Steps
+
+### Step 0: Diff Scope Extraction
+
+이번 스프린트에서 **실제로 수정된 파일만** 검사한다:
+
+```bash
+git diff --name-only <sprint_base>..HEAD
+```
+
+- 수정 파일이 없으면 즉시 FAIL (스프린트 자체가 빈 상태).
+- 수정 파일 수가 너무 많으면 (>50 변경) Planner 에스컬레이션 고려.
+
+### Step 1: Static Toolchain Execution
+
+결정론적 검사를 먼저 돌려 근본적 문제를 배제:
+
+- `tsc --noEmit` (전체 or 영향 패키지)
+- `eslint <변경 파일>` (biome 있으면 `biome check`)
+- 프로젝트가 제공하는 lint/type check 스크립트 (`npm run lint:quality` 등)
+
+**하나라도 error 레벨 실패 → 즉시 FAIL** (나머지 축 채점 전 조기 종료).
+
+### Step 2: C1-C5 축별 코드 리딩
+
+변경 파일을 각 축으로 읽어 evidence 수집. 상세 루브릭 → [scoring-rubric](references/scoring-rubric.md)
+
+| # | 축 | 무엇을 보는가 | Weight |
+|---|----|--------------|--------|
+| C1 | Layer & Boundary | IA-MAP/MSA 경계 준수, 레이어 역방향 의존 없음, FE VM↔View 경계 | 25% |
+| C2 | Readability & Complexity | 네이밍, 함수 길이/중첩, 매직 넘버, 주석 남용/부재, dead code | 15% |
+| C3 | Reuse & DRY | 기존 util/hook/dto 활용, 중복 로직 없음, 조기 추상화 아님 | 20% |
+| C4 | Type Safety & Error Handling | `any` 남용, null 처리, 예외 전파 경로, 경계 입력 검증 | 25% |
+| C5 | Test Quality | 행동 기반 (not 구현 결합), mock 남용 없음, AC 매핑, 커버리지 의미 | 15% |
+
+### Step 3: Cross-Reference With Contracts
+
+- `api-contract.json` ↔ 실제 DTO/controller 시그니처 불일치 감지
+- `feature-list.json` 의 feature 경계 ↔ 구현 파일 위치 IA-MAP 준수
+
+### Step 4: Verdict
+
+- 가중 점수 < 2.80 → FAIL
+- 축 하나라도 Score 0 → FAIL (evidence 없는 Score 는 0 강제)
+- Step 1 toolchain 실패 → FAIL
+- Contract 불일치 1건 이상 → FAIL
+
+### Step 5: Output
+
+`actions/evaluation-code-quality.md` 작성:
+
+- 축별 Score(0-3), 근거 evidence (파일:라인), 개선 제안
+- Toolchain 실행 로그 요약
+- 수정 파일 목록 + diff 통계
+- 최종 Verdict + 재작업 대상 (retry_target)
+
+Cross-Validation 데이터 블록 포함 (Functional/Visual 이 참조):
+
+```json
+{
+  "cross_validation_from_code_quality": {
+    "layer_violations": [...],
+    "type_holes": [...],
+    "contract_divergence": [...]
+  }
+}
+```
+
+## Adversarial Rules
+
+- "동작하니 PASS" 금지. 여기서는 구조를 본다.
+- "이번 스프린트 외 코드라 건너뜀" 금지. 변경 파일 범위 안에서는 전수 검사.
+- Evidence (파일:라인) 없는 Score = 0.
+- "사소한 중복", "관용적 any" 같은 자기설득 금지.
+- Generator가 이미 같은 패턴을 반복 제출 중이면 **반복 페널티** (같은 축에서 이전 스프린트 대비 악화 → Score 최대 1).
+- 리팩토링 제안만 하고 Pass 주는 건 금지 — 제안이 필수 개선이면 FAIL.
+
+## Forbidden
+
+- 브라우저/서버 기동
+- 코드 수정/커밋
+- "Functional 에서 확인하세요" 식의 책임 전가 (여기서 코드로 확인 가능한 것은 여기서 한다)
+- "시간 제약" 핑계 — 변경 범위는 유한하다
+
+## After Evaluation
+
+- **PASS** → Session Boundary Protocol On Complete (PASS) 실행
+- **FAIL** → Session Boundary Protocol On Fail 실행

package/skills/evaluator-code-quality/references/scoring-rubric.md

@@ -0,0 +1,104 @@
+---
+docmeta:
+  id: scoring-rubric
+  title: Code-Quality Scoring Rubric
+  type: output
+  createdAt: 2026-04-22T00:00:00Z
+  updatedAt: 2026-04-22T00:00:00Z
+  source:
+    producer: agent
+    skillId: harness-evaluator-code-quality
+  inputs:
+    - documentId: harness-evaluator-code-quality-skill
+      uri: ../SKILL.md
+      relation: output-from
+      sections:
+        - sourceRange:
+            startLine: 76
+            endLine: 84
+          targetRange:
+            startLine: 20
+            endLine: 85
+  tags:
+    - evaluator
+    - code-quality
+    - rubric
+---
+
+# Code-Quality Scoring Rubric (C1-C5)
+
+Score 척도: 0 (Evidence 없음 / Critical 위반) · 1 (Major 위반) · 2 (Minor 위반) · 3 (위반 없음 + 긍정 evidence)
+
+## C1. Layer & Boundary (25%)
+
+**본다:**
+- AGENTS.md IA-MAP 을 위반하는 import (예: FE에서 BE internal 참조)
+- MSA 서비스 간 직접 DB 접근 (메시지 패턴이 원칙)
+- Backend: controller → service → repo 단방향. 역방향/건너뜀 금지.
+- Frontend: view 가 fetch/store 를 직접 조작하지 않고 VM/hook 경유
+- libs/shared-dto 가 apps/ 를 역참조하지 않음
+
+**0점 조건:** 레이어 역방향 의존 1건 이상, 또는 MSA 경계 위반.
+
+## C2. Readability & Complexity (15%)
+
+**본다:**
+- 함수/메서드 50줄 초과, 중첩 4단 초과
+- 매직 넘버/문자열 (상수화 없음)
+- 네이밍: 역할을 말하지 않는 이름 (`data`, `tmp`, `handle`)
+- 주석이 what을 설명 (코드로 말해야 함) / 왜를 빠뜨림
+- dead code, 주석 처리된 블록
+
+**0점 조건:** 300줄 이상 단일 함수, 또는 다수의 dead code 블록 방치.
+
+## C3. Reuse & DRY (20%)
+
+**본다:**
+- 이미 존재하는 util/hook/service 를 무시하고 재구현
+- 3회 이상 반복되는 동일 로직
+- 조기 추상화 (단 1회 사용하는 generic factory 등) — 반대 방향 위반
+- lib/shared-dto 확장 없이 로컬 DTO 중복 선언
+
+**0점 조건:** 기존 util 무시하고 동일 로직 3건+ 재구현.
+
+## C4. Type Safety & Error Handling (25%)
+
+**본다:**
+- `any`, `as any`, `@ts-ignore`, `@ts-expect-error` — 각 건 근거 필수
+- nullable 무시, non-null 단언(`!`) 남용
+- try/catch 가 오류를 삼킴 (`catch {}`, `catch(e) { console.log }`)
+- 경계(API/외부 입력)에서 zod/class-validator 등 검증 부재
+- 비동기 race / unhandled promise
+
+**0점 조건:** unhandled promise 1건 이상, 또는 비타당한 `any` 3건 이상.
+
+## C5. Test Quality (15%)
+
+**본다:**
+- 테스트가 구현 세부(내부 함수 호출 순서)에 결합
+- mock 남용 — 실제 계약이 아닌 스텁 세계를 검증
+- AC 와 테스트 케이스 매핑 부재
+- 행복 경로만, 엣지/에러 케이스 없음
+- 커버리지 숫자 채우기용 (`expect(x).toBeDefined()`)
+
+**0점 조건:** 신규 기능에 테스트 0건, 또는 AC와 매핑되는 테스트 0건.
+
+## Weighted Verdict
+
+```
+Weighted = C1*0.25 + C2*0.15 + C3*0.20 + C4*0.25 + C5*0.15
+PASS  : Weighted >= 2.80 AND 모든 축 Score > 0
+FAIL  : Weighted < 2.80 OR any axis = 0 OR toolchain error OR contract divergence
+```
+
+## Evidence 형식
+
+모든 Score 주장은 아래 형식의 evidence 를 동반해야 한다:
+
+```
+[C4:1] apps/service-user/src/user.service.ts:42
+  - `result as any` 로 타입 우회. DTO 정의 존재(libs/shared-dto/user.dto.ts:15)에도
+    불구하고 강제 캐스팅. 타당한 사유 없음.
+```
+
+Evidence 없는 Score 는 **자동 0점 재계산**.