@walwal-harness/cli 5.7.3 → 5.8.1

package/commands/harness-next.md

@@ -0,0 +1,80 @@
+---
+docmeta:
+  id: harness-next
+  title: /harness-next — 다음 에이전트로 자동 진행
+  type: input
+  createdAt: 2026-04-27T00:00:00Z
+  updatedAt: 2026-04-27T00:00:00Z
+  source:
+    producer: user
+    skillId: harness
+  inputs: []
+  tags: [harness, solo-mode, orchestration, command]
+---
+
+# /harness-next — 다음 에이전트로 자동 진행
+
+현재 에이전트의 완료 상태(`progress.json`)를 읽고 파이프라인 시퀀스에 따라 **다음 에이전트로 자동 진행**합니다. Solo 모드에서 매 단계마다 사용자가 직접 bash 명령을 칠 필요 없이 자동 핸드오프합니다.
+
+## 실행 절차
+
+### Step 1: harness-next.sh 실행
+
+```bash
+bash scripts/harness-next.sh .
+```
+
+스크립트가 수행하는 작업:
+- `progress.json` 읽기 → `current_agent`, `agent_status`, `next_agent` 확인
+- Pre-Eval Gate (lint/type/test) 실행 — Generator → Evaluator 전환 시
+- Artifact prerequisite 검증
+- `.harness/handoff.json` 생성 (다음 에이전트 컨텍스트)
+- 에스컬레이션 체크 (3회 실패 시 → Planner)
+- 마지막 에이전트면 자동 archive 실행
+
+### Step 2: handoff.json 읽고 다음 에이전트 호출
+
+```bash
+cat .harness/handoff.json | jq '{from, to, sprint, prompt, model, thinking_mode, failure_context}'
+```
+
+`to` 필드 값에 따라 자동으로 해당 스킬을 호출합니다:
+
+| `to` 값 | 호출할 스킬 |
+|---------|------------|
+| `dispatcher` | `harness-dispatcher` |
+| `brainstorming` | `harness-brainstorming` |
+| `planner` | `harness-planner` |
+| `generator-backend` | `harness-generator-backend` |
+| `generator-frontend` | `harness-generator-frontend` |
+| `generator-frontend-flutter` | `harness-generator-frontend-flutter` |
+| `evaluator-code-quality` | `harness-evaluator-code-quality` |
+| `evaluator-functional` | `harness-evaluator-functional` |
+| `evaluator-functional-flutter` | `harness-evaluator-functional-flutter` |
+| `evaluator-visual` | `harness-evaluator-visual` |
+| `archive` | (자동 처리됨, 새 dispatch 대기) |
+| `null` (blocked) | 멈춤. 사용자에게 차단 사유 안내 |
+
+### Step 3: 호출된 스킬이 handoff.json을 컨텍스트로 사용
+
+`handoff.json.prompt` 에 thinking mode, sprint, 실패 컨텍스트가 포함되어 있으므로 그대로 사용합니다.
+
+## 사용 시점
+
+- **자동 호출** (스킬이 알아서):
+  - Dispatcher, Generator-*, Evaluator-* 완료 직후 (사용자 검토 게이트 없음)
+  - Planner / Brainstorming은 **사용자 승인 후** 스킬이 호출
+- **수동 호출** (사용자가 직접 입력):
+  - 흐름이 멈춰서 다시 진행시키고 싶을 때
+  - Eval FAIL 후 재시도를 시작할 때
+  - `/harness-stop` 이후 재개
+
+## Team 모드와의 관계
+
+Team 모드는 Lead worker가 자체 오케스트레이션 루프를 돌리므로 `/harness-next`가 필요 없습니다. 이 명령은 **Solo 모드 전용**입니다.
+
+## 관련 명령
+
+- `/harness-solo` — Solo 모드 진입/전환
+- `/harness-team` — Team 모드 진입
+- `/harness-stop` — 진행 중단

package/commands/harness-solo.md

@@ -1,3 +1,17 @@
+---
+docmeta:
+  id: harness-solo
+  title: /harness-solo — Solo Mode 시작/전환
+  type: input
+  createdAt: 2026-04-20T00:00:00Z
+  updatedAt: 2026-04-27T00:00:00Z
+  source:
+    producer: user
+    skillId: harness
+  inputs: []
+  tags: [harness, solo-mode, command]
+---
+
 # /harness-solo — Solo Mode 시작/전환
 
 프롬프트 기반으로 하네스 파이프라인을 순차 진행합니다.
@@ -53,8 +67,13 @@ progress.json의 `next_agent` 필드를 확인하여 다음 단계를 안내합
 
 ### Step 4: Solo 모드 진행
 
-사용자가 프롬프트로 각 에이전트 스킬을 호출하여 순차 진행합니다.
-각 에이전트 완료 시 harness-next.sh가 자동으로 다음 에이전트를 결정합니다.
+각 에이전트는 완료 즉시 **`/harness-next` 슬래시 명령을 자동 호출** 하여 다음 에이전트로 핸드오프합니다 (사용자가 매번 bash 명령을 칠 필요 없음).
+
+**예외 — 사용자 승인 게이트가 있는 단계:**
+- **Brainstorming**: brainstorm-spec.md 완성 후 사용자 승인 대기 → 승인 시 자동 `/harness-next`
+- **Planner**: plan.md / api-contract.json 완성 후 사용자 승인 대기 → 승인 시 자동 `/harness-next`
+
+흐름이 멈췄거나 수동으로 다음 단계를 트리거하고 싶으면 사용자가 직접 `/harness-next` 입력 가능.
 
 feature-queue.json이 존재하는 경우:
 - 피처 완료(evaluator PASS) 시 `bash scripts/harness-queue-manager.sh pass {FEATURE_ID} .`를 호출하여 공유 상태 업데이트

package/commands/harness-team.md

@@ -269,6 +269,13 @@ LOG="$HARNESS_ROOT/.harness/progress.log"
 logev() { echo "$(date +'%Y-%m-%d %H:%M') | team-{N} | $1 | $2" >> "$LOG"; }
 ```
 
+**⚠ Prefix 규칙 (필수, 위반 금지)**
+
+- 두 번째 필드($2)는 **반드시 `team-{N}`** 으로 통일한다 (`{N}` 자리에 팀 번호).
+- Worker 가 "evaluator 분간이 더 깔끔해 보인다" 는 이유로 `eval-{N}`, `gen-fe-{N}`, `worker-{N}` 등으로 임의 변경하지 말 것. Dashboard/monitor 의 team panel 필터가 prefix 단위로 매칭하며, 과거 실제로 `eval-{N}` 변형 때문에 7개 워커의 evaluator 라인이 패널에서 모두 누락된 사고가 있었다.
+- Generator 와 Evaluator 의 구분은 prefix 가 아니라 **action 필드($3)** 에서 한다: `gen-*` vs `eval-*` action 으로 충분히 색상/아이콘 분리됨.
+- monitor 필터는 `team-{N}` 외 변형도 매칭하도록 robust 하게 보강되었지만, 그래도 위 규칙은 단일 진실의 원천으로 유지한다.
+
 | ACTION | 사용 시점 | DETAIL 예시 (필수 포함 정보) |
 |--------|-----------|------------------------------|
 | `gen-start`  | Gen Phase 시작 (1회) | `F-001 "사용자 회원가입 API" start — goal=POST /users, 6 AC` — **Feature 제목+목표** 포함 필수 |
@@ -337,6 +344,8 @@ LOG=\"$HARNESS_ROOT/.harness/progress.log\"
 logev() { echo \"$(date +'%Y-%m-%d %H:%M') | team-{N} | $1 | $2\" >> \"$LOG\"; }
 ```
 
+**⚠ 두 번째 필드($2)는 반드시 `team-{N}` 그대로 사용.** Evaluator 라고 `eval-{N}` 으로 바꾸지 말 것 — dashboard/monitor 가 prefix 로 팀을 묶어 렌더링하므로 변형 시 패널에서 라인이 누락된다. Generator/Evaluator 구분은 action 필드($3 = `gen-*` / `eval-*`)에서 자동으로 된다.
+
 **로깅 시점:**
 1. 평가 시작 즉시: `logev eval-start \"{FEATURE_ID} evaluating — {AC수} ACs\"`
 2. 각 AC 검증 후: `logev eval-check \"{FEATURE_ID} AC-{N}: [PASS/FAIL] {근거 요약}\"`

package/package.json

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

@@ -197,10 +197,22 @@ render_team_queue_summary() {
   ready=$(jq '.queue.ready | length' "$QUEUE" 2>/dev/null || echo 0)
   blocked=$(jq '.queue.blocked | length' "$QUEUE" 2>/dev/null || echo 0)
   in_prog=$(jq '.queue.in_progress | length' "$QUEUE" 2>/dev/null || echo 0)
-  passed=$(jq '.queue.passed | length' "$QUEUE" 2>/dev/null || echo 0)
   failed=$(jq '.queue.failed | length' "$QUEUE" 2>/dev/null || echo 0)
-  ready=${ready:-0}; blocked=${blocked:-0}; in_prog=${in_prog:-0}; passed=${passed:-0}; failed=${failed:-0}
-  total=$((ready + blocked + in_prog + passed + failed))
+
+  # passed 는 queue.passed ∪ feature-list.json 의 self-passed 를 dedup 합집합으로 계산
+  # (과거 sprint 에서 PASS 되어 queue 에서 빠진 feature 도 카운트)
+  if [ -f "$FEATURES" ]; then
+    passed=$(jq -r --slurpfile q "$QUEUE" '
+      ($q[0].queue.passed // []) as $qp |
+      ([.features[] | select((.passes // []) | any(. == "evaluator-functional" or . == "evaluator-visual" or . == "evaluator-code-quality")) | .id]) as $sp |
+      ($qp + $sp | unique | length)
+    ' "$FEATURES" 2>/dev/null || echo 0)
+    total=$(jq '.features | length' "$FEATURES" 2>/dev/null || echo 0)
+  else
+    passed=$(jq '.queue.passed | length' "$QUEUE" 2>/dev/null || echo 0)
+    total=$((ready + blocked + in_prog + passed + failed))
+  fi
+  ready=${ready:-0}; blocked=${blocked:-0}; in_prog=${in_prog:-0}; passed=${passed:-0}; failed=${failed:-0}; total=${total:-0}
 
   local pct=0
   if [ "$total" -gt 0 ]; then pct=$(( passed * 100 / total )); fi
@@ -274,7 +286,11 @@ render_team_features() {
     .features[] |
     .id as $fid |
     (.name // .title // .description // "?" | if length > 18 then .[0:16] + ".." else . end) as $fname |
-    (if ($fid | IN($passed[])) then "P"
+    # passed 판정: queue.passed 또는 feature.passes 에 evaluator-functional/visual/code-quality 가 있으면 PASS.
+    # 과거 sprint 에서 PASS 된 feature 가 새 sprint queue 재생성 시 queue.passed 에서 누락되어도
+    # feature-list.json 의 passes 배열은 이력으로 남아있으므로, 거기서도 검사한다.
+    ((.passes // []) | any(. == "evaluator-functional" or . == "evaluator-visual" or . == "evaluator-code-quality")) as $self_passed |
+    (if ($fid | IN($passed[])) or $self_passed then "P"
      elif $prog[$fid] then "I|\($prog[$fid].team)|\($prog[$fid].phase)"
      elif ($fid | IN($failed[])) then "F"
      elif ($fid | IN($ready[])) then "R"

package/scripts/harness-monitor.sh

@@ -137,7 +137,16 @@ render_team_section() {
   local have_logs=0
   if [ -f "$PROGRESS_LOG" ]; then
     local matched
-    matched=$(grep -E "team-${team_num}\b|team_${team_num}\b" "$PROGRESS_LOG" 2>/dev/null | tail -"$log_lines")
+    # Team panel 필터: agent 필드($2)가 해당 team 번호를 포함하는 모든 prefix 매칭.
+    # 허용: team-N, team_N, eval-N, eval_N, gen-N, gen-fe-N, worker-N, lead-N 등
+    # (워커가 evaluator 분리를 위해 eval-N 으로 로깅해도 누락되지 않게 한다)
+    matched=$(awk -F'|' -v n="${team_num}" '
+      {
+        # $2 = agent (앞뒤 공백 trim)
+        a=$2; gsub(/^ +| +$/,"",a)
+        # agent 토큰이 [-_]N\b 로 끝나거나 -N- / _N_ 처럼 N이 토큰 경계에 포함되면 매치
+        if (match(a, "(^|[-_])" n "([-_]|$)")) print
+      }' "$PROGRESS_LOG" 2>/dev/null | tail -"$log_lines")
     if [ -n "$matched" ]; then
       have_logs=1
       local cols

package/skills/brainstorming/SKILL.md

@@ -69,8 +69,9 @@ jq '.agent_status = "completed" | .completed_agents += ["planner"]'   .harness/p
    - `completed_agents` 에 `"brainstormer"` 추가
    - `next_agent` → `"planner"`
 3. `.harness/progress.log` 에 요약 추가: `Brainstormer → Planner (spec: <경로>)`
-4. **STOP. 다음 에이전트를 직접 호출하지 않는다.**
-5. 출력: `"✓ Brainstormer 완료. bash scripts/harness-next.sh 실행하여 Planner 단계로 진행."`
+4. 출력: `"✓ Brainstormer 완료. brainstorm-spec.md 검토 후 승인 신호를 주세요. 승인 시 /harness-next 자동 진행 (Planner)."`
+5. **사용자 승인 게이트**: 사용자의 명시적 승인 ("이 디자인 승인한다", "ok", "다음", "Planner 가자" 등) 을 기다린 후, **`/harness-next` 슬래시 명령을 호출하여 Planner 로 자동 핸드오프**.
+6. 사용자가 피드백/수정 요청을 하면 brainstorm-spec.md 를 갱신하고 다시 승인 요청. 승인 없이는 `/harness-next` 호출 금지 (HARD-GATE 준수).
 
 ### On Fail / Abort
 사용자가 중간에 "중단" / "취소" / "abort" 를 요청하면:

package/skills/dispatcher/SKILL.md

@@ -55,8 +55,8 @@ jq '.agent_status = "completed" | .completed_agents += ["planner"]'   .harness/p
      ```
      아카이빙 후 `dispatch.id` 는 `null` 로 리셋되므로, 다음 dispatcher 실행 시 새 D-NNN 이 할당된다.
 2. `.harness/progress.log`에 요약 한 줄 추가
-3. **STOP. 다음 에이전트를 직접 호출하지 않는다.**
-4. 출력: `"✓ Dispatcher 완료. bash scripts/harness-next.sh 실행하여 다음 단계 확인."`
+3. 출력: `"✓ Dispatcher 완료. /harness-next 자동 진행."`
+4. **즉시 `/harness-next` 슬래시 명령을 호출하여 다음 에이전트로 자동 핸드오프** (Solo 모드. Team 모드는 Lead가 별도 오케스트레이션). Brainstorming/Planner 단계가 아니면 사용자 승인 게이트 없음.
 
 ## Auto-Routing (UserPromptSubmit Hook)
 

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

@@ -41,8 +41,8 @@ jq '.agent_status = "completed" | .completed_agents += ["planner"]'   .harness/p
    - `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 실행하여 다음 단계 확인."`
+4. 출력: `"✓ Evaluator-Code-Quality PASS. /harness-next 자동 진행."`
+5. **즉시 `/harness-next` 슬래시 명령을 호출하여 다음 에이전트로 자동 핸드오프** (Solo 모드. Team 모드는 Lead가 별도 오케스트레이션).
 
 ### On Fail
 1. progress.json 업데이트:
@@ -55,8 +55,8 @@ jq '.agent_status = "completed" | .completed_agents += ["planner"]'   .harness/p
    - `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 실행하여 재작업 대상 확인."`
+4. 출력: `"✖ Evaluator-Code-Quality FAIL. /harness-next 자동 진행 (재작업 대상으로 라우팅)."`
+5. **즉시 `/harness-next` 슬래시 명령을 호출하여 `failure.retry_target` 으로 자동 핸드오프** (Solo 모드).
 
 ## Critical Mindset
 

package/skills/evaluator-functional/SKILL.md

@@ -43,8 +43,8 @@ jq '.agent_status = "completed" | .completed_agents += ["planner"]'   .harness/p
    - `failure` 필드 초기화
 3. `feature-list.json`의 통과 feature `passes`에 `"evaluator-functional"` 추가
 4. `.harness/progress.log`에 PASS 요약 추가
-5. **STOP. 다음 에이전트를 직접 호출하지 않는다.**
-6. 출력: `"✓ Evaluator-Functional PASS. bash scripts/harness-next.sh 실행하여 다음 단계 확인."`
+5. 출력: `"✓ Evaluator-Functional PASS. /harness-next 자동 진행."`
+6. **즉시 `/harness-next` 슬래시 명령을 호출하여 다음 에이전트로 자동 핸드오프** (Solo 모드. Team 모드는 Lead가 별도 오케스트레이션).
 
 ### On Fail
 1. **Screenshot Cleanup** — PASS 와 동일하게 스크린샷 파일 삭제 (FAIL 시에도 정리 필수).
@@ -58,8 +58,8 @@ jq '.agent_status = "completed" | .completed_agents += ["planner"]'   .harness/p
    - `sprint.retry_count` 증가
 3. `sprint.retry_count >= 10`이면 `agent_status` → `"blocked"`, 사용자 개입 요청
 4. `.harness/progress.log`에 FAIL 요약 추가
-5. **STOP.**
-6. 출력: `"✖ Evaluator-Functional FAIL. bash scripts/harness-next.sh 실행하여 재작업 대상 확인."`
+5. 출력: `"✖ Evaluator-Functional FAIL. /harness-next 자동 진행 (재작업 대상으로 라우팅)."`
+6. **즉시 `/harness-next` 슬래시 명령을 호출하여 `failure.retry_target` 으로 자동 핸드오프** (Solo 모드).
 
 ## Critical Mindset
 

package/skills/evaluator-visual/SKILL.md

@@ -43,8 +43,8 @@ jq '.agent_status = "completed" | .completed_agents += ["planner"]'   .harness/p
    - `failure` 필드 초기화
 3. `feature-list.json`의 통과 feature `passes`에 `"evaluator-visual"` 추가
 4. `.harness/progress.log`에 PASS 요약 추가
-5. **STOP. 다음 에이전트를 직접 호출하지 않는다.**
-6. 출력: `"✓ Evaluator-Visual PASS. bash scripts/harness-next.sh 실행하여 아카이브 진행."`
+5. 출력: `"✓ Evaluator-Visual PASS. /harness-next 자동 진행 (아카이브)."`
+6. **즉시 `/harness-next` 슬래시 명령을 호출하여 아카이브 단계로 자동 핸드오프** (Solo 모드. Team 모드는 Lead가 별도 오케스트레이션).
 
 ### On Fail
 1. **Screenshot Cleanup** — PASS 와 동일하게 스크린샷 파일 삭제 (FAIL 시에도 정리 필수).
@@ -58,8 +58,8 @@ jq '.agent_status = "completed" | .completed_agents += ["planner"]'   .harness/p
    - `sprint.retry_count` 증가
 3. `sprint.retry_count >= 10`이면 `agent_status` → `"blocked"`, 사용자 개입 요청
 4. `.harness/progress.log`에 FAIL 요약 추가
-5. **STOP.**
-6. 출력: `"✖ Evaluator-Visual FAIL. bash scripts/harness-next.sh 실행하여 재작업 대상 확인."`
+5. 출력: `"✖ Evaluator-Visual FAIL. /harness-next 자동 진행 (재작업 대상으로 라우팅)."`
+6. **즉시 `/harness-next` 슬래시 명령을 호출하여 `failure.retry_target` 으로 자동 핸드오프** (Solo 모드).
 
 ## FE Playwright Mandatory Rule (v5.4)
 

package/skills/generator-backend/SKILL.md

@@ -39,8 +39,8 @@ jq '.agent_status = "completed" | .completed_agents += ["planner"]'   .harness/p
    - `failure` 필드 초기화 (retry 성공 시)
 2. `feature-list.json` 의 해당 feature `passes` 에 `"generator-backend"` 추가
 3. `.harness/progress.log` 에 요약 추가
-4. **STOP. 다음 에이전트를 직접 호출하지 않는다.**
-5. 출력: `"✓ Generator-Backend 완료. bash scripts/harness-next.sh 실행하여 다음 단계 확인."`
+4. 출력: `"✓ Generator-Backend 완료. /harness-next 자동 진행."`
+5. **즉시 `/harness-next` 슬래시 명령을 호출하여 다음 에이전트로 자동 핸드오프** (Solo 모드. Team 모드는 Lead가 별도 오케스트레이션).
 
 ## Startup (Adaptive Loading)
 

package/skills/generator-frontend/SKILL.md

@@ -39,8 +39,8 @@ jq '.agent_status = "completed" | .completed_agents += ["planner"]'   .harness/p
    - `failure` 필드 초기화 (retry 성공 시)
 2. `feature-list.json` 의 해당 feature `passes` 에 `"generator-frontend"` 추가
 3. `.harness/progress.log` 에 요약 추가
-4. **STOP. 다음 에이전트를 직접 호출하지 않는다.**
-5. 출력: `"✓ Generator-Frontend 완료. bash scripts/harness-next.sh 실행하여 다음 단계 확인."`
+4. 출력: `"✓ Generator-Frontend 완료. /harness-next 자동 진행."`
+5. **즉시 `/harness-next` 슬래시 명령을 호출하여 다음 에이전트로 자동 핸드오프** (Solo 모드. Team 모드는 Lead가 별도 오케스트레이션).
 
 ## Startup (Adaptive Loading)
 

package/skills/planner/SKILL.md

@@ -36,8 +36,9 @@ jq '.agent_status = "completed" | .completed_agents += ["planner"]'   .harness/p
    - `completed_agents`에 `"planner"` 추가
    - `next_agent` → 파이프라인에 따라 결정 (FULLSTACK/BE-ONLY: `"generator-backend"`, FE-ONLY: `"generator-frontend"`)
 2. `.harness/progress.log`에 요약 추가
-3. **STOP. 다음 에이전트를 직접 호출하지 않는다.**
-4. 출력: `"✓ Planner 완료. bash scripts/harness-next.sh 실행하여 다음 단계 확인."`
+3. 출력: `"✓ Planner 완료. plan.md / api-contract.json 검토 후 승인 신호를 주세요. 승인 시 /harness-next 자동 진행."`
+4. **사용자 승인 게이트**: 사용자의 명시적 승인 ("승인", "ok", "다음", "진행", "go" 등) 을 기다린 후, **`/harness-next` 슬래시 명령을 호출하여 다음 에이전트로 자동 핸드오프**.
+5. 사용자가 피드백/수정 요청을 하면 plan.md / feature-list.json / api-contract.json 을 갱신하고 다시 승인 요청. 승인 없이는 `/harness-next` 호출 금지.
 
 ## Startup