@walwal-harness/cli 5.6.4 → 5.6.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@walwal-harness/cli",
-  "version": "5.6.4",
+  "version": "5.6.5",
   "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-next.sh

@@ -54,7 +54,7 @@ if [ -f "$PIPELINE_JSON" ]; then
   fe_target=$(jq -r '.fe_target // empty' "$PIPELINE_JSON" 2>/dev/null || true)
   if [ -z "$fe_target" ]; then
     # pipeline.json 에 fe_target 미지정 시 config.json 의 _default_target 사용
-    fe_target=$(jq -r ".flow.pipeline_selection.fe_stack_substitution.${fe_stack}._default_target // \"web\"" "$CONFIG" 2>/dev/null || echo "web")
+    fe_target="web"  # v5.6.5+: 치환 로직 제거. fe_target 은 pipeline.json 에서 명시하거나 web 기본.
   fi
 fi
 

package/scripts/lib/harness-guardrail.sh

@@ -29,9 +29,10 @@ get_allowed_paths() {
       echo "tsconfig"
       echo "docker-compose"
       ;;
-    generator-frontend|generator-frontend-flutter)
+    generator-frontend)
       echo "apps/web/"
       echo "apps/flutter/"
+      echo "lib/"
       echo ".harness/actions/sprint-contract.md"
       echo ".harness/actions/feature-list.json"
       echo ".harness/progress.json"
@@ -43,7 +44,7 @@ get_allowed_paths() {
       echo ".harness/actions/evaluation-code-quality.md"
       echo ".harness/progress.json"
       ;;
-    evaluator-functional|evaluator-functional-flutter)
+    evaluator-functional)
       echo ".harness/actions/evaluation-functional.md"
       echo ".harness/progress.json"
       echo "tests/"

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

@@ -311,7 +311,7 @@ render_agent_bar() {
     fe_stack=$(jq -r '.fe_stack // "react"' "$PIPELINE_JSON" 2>/dev/null || echo "react")
     fe_target=$(jq -r '.fe_target // empty' "$PIPELINE_JSON" 2>/dev/null || true)
     if [ -z "$fe_target" ]; then
-      fe_target=$(jq -r ".flow.pipeline_selection.fe_stack_substitution.${fe_stack}._default_target // \"web\"" "$CONFIG" 2>/dev/null || echo "web")
+      fe_target="web"  # v5.6.5+: 치환 로직 제거. 기본 web.
     fi
   fi
 
@@ -325,14 +325,7 @@ render_agent_bar() {
 
   while IFS= read -r agent; do
     agent=$(echo "$agent" | sed 's/:.*//')  # strip mode suffix like :light, :api-only
-
-    # fe_stack + fe_target 치환 적용
-    if [ "$fe_stack" = "flutter" ]; then
-      local sub
-      sub=$(jq -r ".flow.pipeline_selection.fe_stack_substitution.flutter.by_target[\"${fe_target}\"][\"${agent}\"] // \"${agent}\"" "$CONFIG" 2>/dev/null)
-      if [ "$sub" = "__skip__" ]; then continue; fi
-      agent="$sub"
-    fi
+    # v5.6.5+: fe_stack 에이전트 치환 제거. 스택별 동작은 ref-docs 로 조절.
 
     if [ "$first" = true ]; then
       first=false

package/skills/dispatcher/SKILL.md

@@ -147,7 +147,7 @@ AGENTS.md 비하네스  → 기존 백업 + 리빌드
 - 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` 는 스택/타겟 무관 공통.
+스택 특성(예: Flutter mobile 에서 Visual skip) 이 필요하면 해당 스택 ref-docs (`.harness/ref/fe-<stack>.md`) 의 `validation.visual.enabled` 를 false 로 두면 evaluator-visual 이 MANUAL_REQUIRED 로 우아하게 우회한다. 별도 치환 에이전트는 사용하지 않는다.
 
 ### Evaluator 체인 라우팅 규칙
 
@@ -163,11 +163,9 @@ Gotcha retry 시에도 체인 시작점은 chain[0] 부터 재실행.
 
 FE-ONLY 또는 FULLSTACK 선택 시, `pipeline.json`에 **`fe_stack`** 필드를 포함해야 한다:
 
-- `scan-result.json.tech_stack.fe_stack` 값을 기본으로 사용 (`react` | `flutter`)
+- `scan-result.json.tech_stack.fe_stack` 값을 기본으로 사용 (예: `react`, `nextjs`, `vue`, `flutter`, `swift` 등)
 - 값이 없거나 불명확하면 Planner가 확정하도록 위임 (Dispatcher는 `"unknown"` 기록 + `notes` 에 메모)
-- Flutter 선택 시 `agents_active`/`agents_skipped`에 치환된 에이전트명을 기록
-  - active: `generator-frontend-flutter`, `evaluator-functional-flutter`
-  - skipped: `generator-frontend`, `evaluator-functional`, `evaluator-visual`
+- **에이전트 이름 치환은 하지 않는다** (v5.6.5+). 모든 FE 스택은 공통 `generator-frontend` / `evaluator-functional` / `evaluator-visual` 을 사용하고, 스택 특성은 `.harness/ref/fe-<stack>.md` (adaptive ref-docs) 에서 로드한다.
 
 ## 6. Brainstormer Routing Decision
 
@@ -222,7 +220,7 @@ Planner 를 호출해야 한다고 판단되면, **사용자에게 단 하나의
 | 상황 | next_agent |
 |------|-----------|
 | "Eval, X 다시 검증해" | `evaluator-functional` (또는 `evaluator-visual`) |
-| "Generator-FE, Y 버그 고쳐" | `generator-frontend` (또는 Flutter 변형) |
+| "Generator-FE, Y 버그 고쳐" | `generator-frontend` |
 | "Generator-BE, API 재생성해" | `generator-backend` |
 | Eval FAIL → retry | `failure.retry_target` |
 | Gotcha 수정 | `failure.retry_target` 또는 현재 에이전트 |
@@ -240,14 +238,8 @@ Planner 를 호출해야 한다고 판단되면, **사용자에게 단 하나의
 이 경우 기존 `.harness/actions/brainstorm-spec.md` 는 Brainstormer 의 On Start 에서
 `.harness/archive/brainstorm-spec-<timestamp>.md` 로 백업된다.
 
-## 7. Handoff 라우팅 (fe_stack 반영)
+## 7. Handoff 라우팅
 
-Dispatcher가 `next_agent` 를 세팅할 때 pipeline.json.fe_stack 을 참조해 치환:
+Dispatcher 가 `next_agent` 를 세팅할 때 **스택별 에이전트 이름 치환은 하지 않는다** (v5.6.5+). 모든 FE 스택이 공통 `generator-frontend` / `evaluator-functional` / `evaluator-visual` 을 사용하고, 스택 특성은 adaptive ref-docs(`.harness/ref/fe-<stack>.md`) 에서 로드한다.
 
-| 원본 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 는 fe_stack 치환 대상이 아니다** — 언어/스택 무관 공통 에이전트.
+예외적 스킵 규칙은 ref-docs 의 `validation.visual.enabled` 플래그로 제어 — false 면 evaluator-visual 이 MANUAL_REQUIRED 로 우아하게 우회한다 (별도 에이전트 이름 변경 없음).

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

@@ -28,35 +28,19 @@ docmeta:
 
 # Pipeline Definitions
 
-> **FE Stack 차원**: 모든 FE 관련 파이프라인은 `fe_stack` 필드로 React/Flutter를 구분한다.
+> **FE Stack 차원**: 모든 FE 관련 파이프라인은 `fe_stack` 필드로 스택을 기록한다.
 > Planner가 scan-result.json(`tech_stack.fe_stack`) 또는 사용자 질문으로 확정한다.
 
-## fe_stack + fe_target 스위치 매트릭스
+## 단일 에이전트 체인 (v5.6.5+)
 
-| fe_stack | fe_target | FE Generator | Eval-Functional | Eval-Visual |
-|----------|-----------|--------------|----------------|-------------|
-| `react`  | (n/a)     | `generator-frontend` | `evaluator-functional` (Playwright) | `evaluator-visual` |
-| `flutter`| **`web`** | `generator-frontend-flutter` | **`evaluator-functional`** (Playwright!) | **`evaluator-visual`** (Playwright!) |
-| `flutter`| `mobile`  | `generator-frontend-flutter` | `evaluator-functional-flutter` (정적 분석) | **SKIP** |
-| `flutter`| `desktop` | `generator-frontend-flutter` | `evaluator-functional-flutter` (정적 분석) | **SKIP** |
+**에이전트 이름 치환은 하지 않는다**. 모든 FE 스택(React, Next.js, Vue, Svelte, Flutter, Swift, 기타) 은 공통 `generator-frontend` / `evaluator-functional` / `evaluator-visual` 을 사용하며, 스택 특성(runner, paths, API, validation) 은 **adaptive ref-docs** (`.harness/ref/fe-<stack>.md`) 에서 로드한다.
 
-> **Flutter Web**: 컴파일 결과가 HTML+JS+CSS 이므로 React 경로의 Playwright evaluator 가 정상 동작.
-> Generator-Frontend-Flutter 의 Self-Verification 에서 `flutter analyze` / `flutter test` /
-> `flutter build web --release` 가 이미 통과한 상태로 handoff 됨이 전제.
+| 스택별 스킵/우회 | 방법 |
+|------------------|------|
+| Visual 렌더 검증이 불가능한 네이티브 모바일/데스크톱 | ref-docs 의 `validation.visual.enabled = false` — `evaluator-visual` 이 MANUAL_REQUIRED 로 우아하게 우회 |
+| Playwright 대신 스택 네이티브 E2E (예: XCUITest, Flutter `flutter_driver`) | ref-docs 의 `validation.functional_tests` 에 해당 명령 나열 — `evaluator-functional` 이 로드 실행 |
 
-Dispatcher는 `next_agent`를 설정할 때 `pipeline.json` 의 `fe_stack` + `fe_target` 두 값을 보고 치환한다:
-
-```
-if pipeline.json.fe_stack == "flutter":
-    "generator-frontend" → "generator-frontend-flutter"  (모든 fe_target 공통)
-
-    if fe_target == "web":
-        "evaluator-functional" → "evaluator-functional"  (그대로, Playwright 사용)
-        "evaluator-visual"     → "evaluator-visual"      (그대로)
-    elif fe_target in ("mobile", "desktop"):
-        "evaluator-functional" → "evaluator-functional-flutter"
-        "evaluator-visual"     → __skip__
-```
+Dispatcher 는 `fe_stack` 을 `pipeline.json` 에 기록만 하고, 에이전트 이름은 변경하지 않는다. Generator/Evaluator 는 세션 시작 시 스스로 ref-docs 를 로드해 스택에 맞는 동작을 한다.
 
 ## Evaluator Chain (공통)
 
@@ -83,10 +67,10 @@ agents:
   - planner (light):
       skip: MSA 서비스 설계, BE 기능 목록
       do: OpenAPI → api-contract.json 변환, FE 컴포넌트 설계, feature-list (layer: frontend만), fe_stack 확정
-  - generator-frontend OR generator-frontend-flutter  # fe_stack에 따라
+  - generator-frontend                                 # 모든 스택 공통 (ref-docs 로드)
   - evaluator-code-quality                             # 공통 — 브라우저 없음
-  - evaluator-functional OR evaluator-functional-flutter
-  - evaluator-visual  # fe_stack == "flutter" + fe_target in (mobile,desktop) 이면 SKIP
+  - evaluator-functional                               # 모든 스택 공통
+  - evaluator-visual                                   # ref.validation.visual.enabled=false 면 MANUAL_REQUIRED 로 우회
 evaluator_chain:
   - evaluator-code-quality
   - evaluator-functional
@@ -95,9 +79,9 @@ skip:
   - generator-backend
 notes:
   - api-contract.json은 OpenAPI에서 파생 (Planner가 변환)
-  - Eval-Func(React)의 API Health Check는 외부 서버 대상
+  - Eval-Func 의 API Health Check는 외부 서버 대상 (ref.api.base_url)
   - AGENTS.md IA-MAP에 BE 경로 없음 (외부 서버)
-  - fe_stack=flutter (mobile/desktop) 인 경우 evaluator-visual 생략
+  - 네이티브 모바일/데스크톱 스택은 ref-docs 에서 visual.enabled=false 로 설정
 ```
 
 ## BE-ONLY

package/skills/planner/SKILL.md

@@ -76,14 +76,15 @@ jq '.agent_status = "completed" | .completed_agents += ["planner"]'   .harness/p
 
 ## fe_stack (FE 파이프라인 분기)
 
-`pipeline.json.fe_stack`은 FE Generator/Evaluator 선택을 결정한다:
+`pipeline.json.fe_stack` 은 스택 기록용 메타데이터이며, **에이전트 이름 치환에는 사용되지 않는다** (v5.6.5+). 모든 스택이 공통 `generator-frontend` / `evaluator-functional` / `evaluator-visual` 을 사용하고, 스택별 동작(runner, paths, API, validation) 은 adaptive ref-docs(`.harness/ref/fe-<stack>.md`) 에서 로드한다.
 
-| 값 | FE Generator | FE Evaluator | 비고 |
-|----|--------------|--------------|------|
-| `react` (기본) | `generator-frontend` | `evaluator-functional` + `evaluator-visual` | Vercel/Next.js/Tailwind |
-| `flutter` | `generator-frontend-flutter` | `evaluator-functional-flutter` | Riverpod + integrated_data_layer, Eval-Visual 생략 |
+| 스택 예 | ref-docs 경로 | 비고 |
+|---------|--------------|------|
+| `react`, `nextjs` | `.harness/ref/fe-react.md`, `.harness/ref/fe-nextjs.md` | Vercel/Next.js/Tailwind |
+| `flutter` | `.harness/ref/fe-flutter.md` | Riverpod · validation.visual.enabled=false (모바일/데스크톱) |
+| `vue`, `svelte`, `swift` 등 | `.harness/ref/fe-<stack>.md` | 각 스택 관례 |
 
-**Planner는 `pipeline.json`에 `fe_stack`을 반드시 기록해야 한다.** Dispatcher가 이 값으로 `next_agent`를 라우팅한다.
+**Planner는 `pipeline.json`에 `fe_stack`을 반드시 기록해야 한다.** Generator/Evaluator 는 세션 시작 시 이 값으로 올바른 ref-docs 를 로드한다.
 
 ## Process
 

package/skills/planner/references/fe-stack-detection.md

@@ -107,72 +107,58 @@ Flutter 프로젝트의 타깃을 확인합니다:
 이번 스프린트의 타깃은? (A/B/C)
 ```
 
-### fe_target → Eval 흐름
+### fe_target 과 Eval 흐름 (v5.6.5+)
 
-| fe_target | Generator | Eval-Functional | Eval-Visual |
-|-----------|-----------|----------------|-------------|
-| `web` | `generator-frontend-flutter` | `evaluator-functional` (Playwright!) | `evaluator-visual` (Playwright!) |
-| `mobile` | `generator-frontend-flutter` | `evaluator-functional-flutter` (정적 분석) | SKIP |
-| `desktop` | `generator-frontend-flutter` | `evaluator-functional-flutter` (정적 분석) | SKIP |
+에이전트 이름 치환은 하지 않는다. 모든 스택이 공통 `generator-frontend` / `evaluator-functional` / `evaluator-visual` 을 사용하고, 스택 특성은 `.harness/ref/fe-<stack>.md` (adaptive ref-docs) 의 `validation` 블록으로 조절된다.
 
-**핵심**: Flutter Web 의 빌드 결과물(HTML/JS/CSS)은 일반 웹앱과 동일하므로 Playwright 기반
-React 경로의 evaluator 를 그대로 재사용한다. Generator-Frontend-Flutter 의 Self-Verification
-단계에서 `flutter analyze`/`flutter test`/`flutter build web` 정적 검증이 이미 통과한 상태로 handoff 된다.
+| fe_target | 전략 | 방법 |
+|-----------|------|------|
+| `web` (Flutter Web, Next.js 등) | 일반 Playwright 평가 | ref.validation.visual.enabled = true |
+| `mobile` (iOS/Android 네이티브) | Visual 은 MANUAL_REQUIRED | ref.validation.visual.enabled = false + functional_tests 에 스택 네이티브 명령 |
+| `desktop` (macOS/Windows/Linux 네이티브) | Visual MANUAL_REQUIRED | 동일 |
+
+Generator 는 `ref.runner.dev_command` / `ref.paths.*` 를 로드해 스택별 빌드·테스트·구조를 따른다.
 
 ## 3. pipeline.json 갱신
 
-`fe_stack` + `fe_target` 확정 후 `pipeline.json`에 반드시 추가:
+`fe_stack` + `fe_target` 확정 후 `pipeline.json` 에 기록:
 
 ```json
 {
   "pipeline": "FULLSTACK",
   "planner_mode": "full",
   "fe_stack": "flutter",
-  "fe_target": "web",
+  "fe_target": "mobile",
   "agents_active": [
     "planner",
     "generator-backend",
-    "generator-frontend-flutter",
-    "evaluator-functional",
-    "evaluator-visual"
-  ],
-  "agents_skipped": [
     "generator-frontend",
-    "evaluator-functional-flutter"
+    "evaluator-code-quality",
+    "evaluator-functional"
   ],
-  "evaluator_mode": "playwright-web",
-  "notes": "Flutter Web — 컴파일 결과가 HTML+JS+CSS 이므로 React 경로의 Playwright evaluator 사용. Generator 의 Self-Verification 에서 flutter analyze/test 통과 전제."
+  "agents_skipped": [],
+  "evaluator_mode": "native",
+  "notes": "Flutter mobile — ref.validation.visual.enabled=false, evaluator-visual 은 MANUAL_REQUIRED 로 우회."
 }
 ```
 
 ### fe_stack + fe_target → 파이프라인 매핑
 
-| pipeline | fe_stack | fe_target | agents_active 예시 |
-|----------|----------|-----------|-------------------|
-| FULLSTACK | react | (n/a) | planner, generator-backend, generator-frontend, evaluator-functional, evaluator-visual |
-| FULLSTACK | flutter | **web** | planner, generator-backend, generator-frontend-flutter, evaluator-functional, evaluator-visual |
-| FULLSTACK | flutter | mobile | planner, generator-backend, generator-frontend-flutter, evaluator-functional-flutter |
-| FULLSTACK | flutter | desktop | planner, generator-backend, generator-frontend-flutter, evaluator-functional-flutter |
-| FE-ONLY | react | (n/a) | planner, generator-frontend, evaluator-functional, evaluator-visual |
-| FE-ONLY | flutter | **web** | planner, generator-frontend-flutter, evaluator-functional, evaluator-visual |
-| FE-ONLY | flutter | mobile | planner, generator-frontend-flutter, evaluator-functional-flutter |
-| BE-ONLY | (무관) | (n/a) | planner, generator-backend, evaluator-functional |
-
-## 4. Flutter 선택 시 추가 작업
-
-Flutter로 확정되면 Planner는:
-
-1. **AGENTS.md IA-MAP** 의 `[FE]` 섹션을 Flutter 구조로 바꿔야 한다.
-   - `apps/web/` → `lib/ui/pages/`, `lib/ui/component/`
-   - `libs/shared-dto/` 대신 `integrated_data_layer/` 경로 등록
-   - 소유자: `→ Generator-Frontend-Flutter`
+| pipeline | 에이전트 체인 (스택 무관) | ref-docs 로 조절되는 부분 |
+|----------|--------------------------|---------------------------|
+| FULLSTACK | planner → gen-be → gen-fe → eval-code-quality → eval-func → eval-visual | Gen/Eval 모두 ref.* 로드 |
+| FE-ONLY | planner(light) → gen-fe → eval-code-quality → eval-func → eval-visual | 동일 |
+| BE-ONLY | planner → gen-be → eval-code-quality → eval-func | visual 체인 없음 |
 
-2. **api-contract.json** 은 언어 중립적이어야 한다 — Planner는 TypeScript 타입이 아니라 **스키마 JSON** 으로만 작성. Flutter Generator가 Retrofit/JsonSerializable로 변환한다.
+## 4. Flutter 등 네이티브 스택 선택 시 추가 작업
 
-3. **feature-list.json** 의 `layer: "frontend"` feature들은 `fe_stack: "flutter"` 태그를 달아서 Evaluator가 구분하도록 한다.
+1. **AGENTS.md IA-MAP** 의 `[FE]` 섹션에 해당 스택 구조 반영 (예: Flutter 면 `lib/ui/pages/`, `integrated_data_layer/` 등).
+2. **api-contract.json** 은 언어 중립 스키마 JSON — Generator 가 스택 타입으로 변환.
+3. **feature-list.json** 의 `layer: "frontend"` feature 에 `fe_stack` 태그 유지 (필터링 용도).
+4. **`.harness/ref/fe-<stack>.md`** 의 `validation` 블록을 스택에 맞게 채워 두기 — 이게 실제 동작을 바꾸는 유일한 지점.
 
 ## 5. 금지
 
 - 파이프라인 실행 도중 `fe_stack` 변경 금지 — 스프린트 경계에서만 가능
-- React/Flutter 코드 혼재 생성 금지 — Generator는 하나의 stack만 담당
+- 서로 다른 스택 코드 혼재 생성 금지 — Generator 는 하나의 stack만 담당
 - 사용자가 명시적으로 한 스택을 지시했는데 감지 결과로 다른 스택을 강제하지 말 것