@walwal-harness/cli 5.9.5 → 5.9.6

package/README.md

@@ -69,25 +69,31 @@ npx walwal-harness team
 #### 대시보드 구성
 
 ```
-┌────────────────────┬──────────────────────────┬───────────┐
-│ Dashboard          │ Gotcha & Memory          │ TEAM 1    │
-│  - pipeline/sprint │  - 활성 에이전트 gotcha   │  Gen|Eval │
-│  - feature 진행도  │  - 나머지 에이전트 요약    ├───────────┤
-│  - queue 상태      │  - SHARED MEMORY          │ TEAM 2    │
-│                    │   (memory.md 최근 N)      │  Gen|Eval │
-├────────────────────┤                          ├───────────┤
-│ Archive Prompt     │                          │ TEAM 3    │
-│  (완료 feature 요약)│                          │  Gen|Eval │
-└────────────────────┴──────────────────────────┴───────────┘
+┌────────────────────┬───────────────┬───────────┐
+│ Dashboard          │ Gotchas       │ TEAM 1    │
+│  - pipeline/sprint │  (활성 에이전트)│  Gen|Eval │
+│  - feature 진행도  ├───────────────┤           │
+│  - queue 상태      │ Conventions   ├───────────┤
+│                    │  (하우스 스타일)│ TEAM 2    │
+├────────────────────┤               │  Gen|Eval │
+│ Archive Prompt     ├───────────────┤           │
+│  (완료 feature 요약)│ Memory        ├───────────┤
+│                    │  (공유 교훈)   │ TEAM 3    │
+│                    │               │  Gen|Eval │
+└────────────────────┴───────────────┴───────────┘
 ```
 
 | 패널 | 내용 | 소스 |
 |------|------|------|
 | **Dashboard** | Pipeline · Sprint · Feature passes · Queue R:B:P · Retry | `harness-dashboard.sh` |
-| **Gotcha & Memory** | 활성 에이전트의 누적 실수 + 나머지 요약 + 공유 메모리 | `harness-gotcha-memory.sh` |
+| **Gotchas** | 활성 에이전트의 누적 실수 (`[G-NNN]`) — v5.9.1 부터 독립 패널 | `harness-gotcha-memory.sh --mode gotcha` |
+| **Conventions** | 하우스 스타일 (`[C-NNN]`) — v5.9.1 부터 독립 패널, 독립 스크롤 | `harness-gotcha-memory.sh --mode conventions` |
+| **Memory** | 공유 교훈 (`memory.md`) — v5.9.1 부터 독립 패널 | `harness-gotcha-memory.sh --mode memory` |
 | **TEAM 1–3** | 각 워커의 현재 feature · phase(Gen/Eval) · 실시간 stdout | `harness-queue-manager.sh` worker loop |
 | **Archive Prompt** | 직전 완료 feature 요약 (다음 팀 컨텍스트 주입용) | archive 디렉토리 |
 
+> **v5.9.1+** Rules 컬럼이 3분할(Gotchas/Conventions/Memory)되어 각각 독립 스크롤됩니다. tmux/iTerm2 모두 동일한 레이아웃을 보장합니다.
+
 ##### Feature 상태 아이콘 (v5.6.4+)
 
 | 아이콘 | 상태 | 의미 |
@@ -220,6 +226,16 @@ Dispatcher 자동 분류:
 
 → Dispatcher 가 `memory.md` 에 `### [M-NNN] ...` 로 기록. Planner 리뷰 후 `unverified → verified` 로 승격.
 
+#### 동적 Gotcha/Convention 자동 등록 (v5.9.0+)
+
+Worker 가 `gen-report-*.md` / `evaluation-*.md` 본문에 `gotcha_candidates` / `convention_candidates` 블록을 작성하면, Lead 가 PASS merge 직후 자동으로 dedup append:
+
+```bash
+bash scripts/harness-gotcha-register.sh . --scan-all
+```
+
+→ 다음 worker spawn 전에 갱신된 gotchas/conventions 가 file system 에 반영. **한 sprint 안에서 발견된 실수를 같은 sprint 의 다음 worker 가 즉시 회피**할 수 있게 됨. Generator 도 mandatory — 모든 에이전트가 후보를 자기 보고서에 남기는 것을 강제합니다.
+
 #### 주의 — 데이터 보존
 
 `npm install` postinstall 은 **누적 엔트리(`[G-NNN]` 또는 `[C-NNN]`)가 있는 파일을 절대 덮어쓰지 않습니다**. 스캐폴드 템플릿인 경우에만 갱신됩니다. v5.5.2 이전 버전은 gotchas 에 이 버그가 있었으므로 `5.6.0+` 사용을 권장합니다.
@@ -470,6 +486,13 @@ jq '.mode = "solo"' .harness/progress.json > /tmp/p.json && mv /tmp/p.json .harn
 - v5.5.2 에서 해결 (postinstall 이 누적 엔트리를 절대 덮어쓰지 않도록 수정).
 - 반드시 `5.5.2+` 사용.
 
+### Dashboard 헤더가 SOLO 인데 실제로는 팀 모드로 돌고 있음
+- v5.9.5 에서 해결. `feature-queue.json.queue.in_progress > 0` 이면 dashboard refresh / tmux 재기동 시 자동으로 `mode=team` 으로 self-heal 합니다.
+- 그 이전 버전: `progress.json` 의 `mode` 만 직접 수정하거나 새 세션을 열어 SessionStart 훅의 heal 을 트리거.
+
+### `progress.json` 손상 시 dashboard crash
+- v5.9.4 에서 해결. invalid JSON 인 경우 안내 메시지로 graceful degrade. 복구 가이드는 dashboard 본문에 inline 표시됩니다.
+
 ---
 
 ## License

package/commands/harness-team.md

@@ -447,6 +447,46 @@ Lead에게 반환 **첫 줄에 반드시 `RATE_LIMIT` 태그 포함**:
 
 ---
 
+## Ad-hoc Feature 추가 — Canonical Path (필수)
+
+Lead 가 sprint 진행 중 핫픽스 / 새 sprint feature 를 추가해야 할 때 **`feature-queue.json` 을 jq 로 직접 편집하면 안 된다**. feature-list.json 과 큐가 갈라져서 dashboard 가 누락 표시하고, Planner/Evaluator 가 AC 를 찾지 못한다.
+
+**금지**:
+```bash
+# ❌ 절대 금지 — feature-list 우회
+jq '.queue.ready += ["F-XXX"]' .harness/actions/feature-queue.json > /tmp/q.json && mv /tmp/q.json .harness/actions/feature-queue.json
+```
+
+**Canonical**:
+```bash
+# ✅ 옵션 1 — 새 sprint 의 정식 feature 들이면 Planner 재호출
+#    Planner 가 feature-list.json 에 sprint=N 으로 append → next-sprint 가 큐 채움.
+
+# ✅ 옵션 2 — 단발 핫픽스면 enqueue 명령 사용 (feature-list append + 큐 insert 원자적)
+cat > /tmp/feat.json <<EOF
+{
+  "id": "F-XXX",
+  "title": "auth refresh token lifecycle hotfix",
+  "sprint": 8,
+  "depends_on": [],
+  "layer": "fe",
+  "service": "frontend",
+  "acceptance_criteria": [{"id":"AC-1","description":"...","type":"manual","verify":{"tool":"grep","steps":["..."]}}]
+}
+EOF
+bash scripts/harness-queue-manager.sh enqueue /tmp/feat.json
+```
+
+**무결성 체크** (Lead 루프 진입 직전 권장):
+```bash
+bash scripts/harness-queue-manager.sh integrity
+# 종료 코드 0 = OK, 1 = orphan feature 발견 (feature-list 에 없는 queue 항목)
+```
+
+이 룰을 위반한 사례: Sprint 8 (2026-04-29) 에 F-716, F-800~F-806 이 jq 직접 편집으로 큐에만 등록되어 dashboard Features 패널에서 800 번대가 모두 누락된 적 있음. **dashboard 는 v5.9.6+ 에서 union 렌더 + orphan 경고로 가시화하지만, 가시화는 차단이 아님 — Lead 가 위 canonical path 만 쓸 것**.
+
+---
+
 ## 핵심 원칙
 
 ### Worker = 1 Feature Only

package/package.json

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

@@ -236,14 +236,23 @@ render_team_queue_summary() {
   failed=$(jq '.queue.failed | length' "$QUEUE" 2>/dev/null || echo 0)
 
   # passed 는 queue.passed ∪ feature-list.json 의 self-passed 를 dedup 합집합으로 계산
-  # (과거 sprint 에서 PASS 되어 queue 에서 빠진 feature 도 카운트)
+  # total 도 feature-list IDs ∪ queue 전체 IDs 합집합으로 계산 — 새 sprint feature 가
+  # queue 에만 추가되고 feature-list 에 누락되어도 누락 없이 카운트 (예: F-800+ Sprint 8)
   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)
+    total=$(jq -r --slurpfile q "$QUEUE" '
+      ([.features[].id]) as $fl |
+      (($q[0].queue.ready // []) +
+       ($q[0].queue.passed // []) +
+       (($q[0].queue.failed // []) | if type == "object" then keys else . end) +
+       (($q[0].queue.in_progress // {}) | keys) +
+       (($q[0].queue.blocked // {}) | keys)) as $qids |
+      ($fl + $qids | unique | 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))
@@ -260,6 +269,24 @@ render_team_queue_summary() {
   for ((i=0; i<empty; i++)); do bar+="░"; done
 
   echo -e "  ${bar} ${passed}/${total} (${pct}%)  R:${GREEN}${ready}${RESET} B:${YELLOW}${blocked}${RESET} P:${CYAN}${in_prog}${RESET} ${GREEN}✓${passed}${RESET} ${RED}✗${failed}${RESET}"
+
+  # Integrity warn — 큐에 있지만 feature-list 에 없는 orphan feature 가 있으면 경고.
+  # 발생 원인: Lead 가 jq 로 큐 직접 편집 (canonical path = enqueue 명령 사용).
+  if [ -f "$FEATURES" ]; then
+    local orphan_count
+    orphan_count=$(jq -r --slurpfile q "$QUEUE" '
+      ([.features[].id]) as $fl |
+      (($q[0].queue.ready // []) +
+       ($q[0].queue.passed // []) +
+       (($q[0].queue.failed // []) | if type == "object" then keys else . end) +
+       (($q[0].queue.in_progress // {}) | keys) +
+       (($q[0].queue.blocked // {}) | keys)) as $qids |
+      ($qids - $fl) | unique | length
+    ' "$FEATURES" 2>/dev/null || echo 0)
+    if [ "${orphan_count:-0}" -gt 0 ]; then
+      echo -e "  ${YELLOW}⚠ ${orphan_count} feature(s) in queue but not in feature-list.json${RESET} ${DIM}(use: queue-manager enqueue)${RESET}"
+    fi
+  fi
 }
 
 render_team_status() {
@@ -313,19 +340,23 @@ render_team_features() {
   echo ""
   echo -e "${BOLD}Features${RESET}"
 
+  # feature-list IDs ∪ queue 전체 IDs 합집합을 iterate.
+  # feature-list 에 등록 안 된 queue-only feature 는 name="(queue)" 로 표시.
   jq -r --slurpfile q "$QUEUE" '
     ($q[0].queue.passed // []) as $passed |
-    ($q[0].queue.failed // []) as $failed |
+    ($q[0].queue.failed // []) as $failed_raw |
+    (if ($failed_raw | type) == "object" then ($failed_raw | keys) else $failed_raw end) as $failed |
     ($q[0].queue.ready // []) as $ready |
     ($q[0].queue.in_progress // {}) as $prog |
     ($q[0].queue.blocked // {}) as $blocked |
-    .features[] |
-    .id as $fid |
-    (.name // .title // .description // "?" | if length > 18 then .[0:16] + ".." else . end) as $fname |
-    # 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 |
+    ([.features[] | {id: .id, name: (.name // .title // .description // "?"), passes: (.passes // [])}]) as $fl |
+    ([$fl[] | {(.id): .}] | add // {}) as $fl_map |
+    (([$fl[].id]) + $ready + $passed + $failed + ($prog | keys) + ($blocked | keys) | unique) as $all_ids |
+    $all_ids[] |
+    . as $fid |
+    ($fl_map[$fid] // {name: "(queue)", passes: []}) as $f |
+    ($f.name | if length > 18 then .[0:16] + ".." else . end) as $fname |
+    (($f.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"

package/scripts/harness-queue-manager.sh

@@ -541,6 +541,126 @@ cmd_resume_probe() {
   exit 1
 }
 
+# ══════════════════════════════════════════
+# enqueue — Append feature to feature-list.json AND insert into queue (canonical path).
+#
+# Lead 가 ad-hoc 핫픽스 / 새 sprint feature 를 추가할 때 jq 로 큐를 직접 편집하면
+# feature-list.json 과 큐가 갈라진다 (실제 사고: F-716, F-800~F-806 이 큐에만 등록).
+# 이 명령은 feature-list append → queue insert (deps 미해소면 blocked) 를 한 트랜잭션으로 처리.
+#
+# Usage: enqueue <feature-json-file>   # 파일 경로
+#        enqueue -                     # stdin 으로 JSON
+#
+# 입력 JSON 최소 필드: {id, title, sprint, depends_on?, layer?, service?, acceptance_criteria?}
+# ══════════════════════════════════════════
+cmd_enqueue() {
+  local input="${1:-}"
+  if [ -z "$input" ]; then
+    echo "[queue] enqueue: feature JSON 파일 경로 또는 '-' (stdin) 필요" >&2
+    exit 1
+  fi
+  if [ ! -f "$FEATURES" ]; then echo "[queue] feature-list.json not found." >&2; exit 1; fi
+  if [ ! -f "$QUEUE" ]; then echo "[queue] feature-queue.json not found. init 먼저." >&2; exit 1; fi
+
+  local feat_json
+  if [ "$input" = "-" ]; then
+    feat_json=$(cat)
+  else
+    feat_json=$(cat "$input")
+  fi
+
+  if ! echo "$feat_json" | jq -e '.id and .title and .sprint' >/dev/null 2>&1; then
+    echo "[queue] enqueue: id/title/sprint 필수 필드 누락" >&2
+    exit 1
+  fi
+
+  local fid
+  fid=$(echo "$feat_json" | jq -r '.id')
+
+  acquire_queue_lock
+
+  if jq -e --arg id "$fid" '.features[] | select(.id == $id)' "$FEATURES" >/dev/null 2>&1; then
+    release_queue_lock
+    echo "[queue] enqueue: $fid 이 feature-list.json 에 이미 존재" >&2
+    exit 1
+  fi
+
+  if jq -e --arg id "$fid" '
+    ($id | IN(.queue.ready[]?,.queue.passed[]?)) or
+    (.queue.in_progress[$id]?) or (.queue.blocked[$id]?) or
+    (.queue.failed[$id]? // (.queue.failed | type == "array" and ($id | IN(.queue.failed[]?))))
+  ' "$QUEUE" >/dev/null 2>&1; then
+    release_queue_lock
+    echo "[queue] enqueue: $fid 이 큐에 이미 존재" >&2
+    exit 1
+  fi
+
+  local tmp_features="${FEATURES}.tmp.$$"
+  if ! jq --argjson new "$feat_json" '.features += [$new]' "$FEATURES" > "$tmp_features" 2>/dev/null; then
+    rm -f "$tmp_features"; release_queue_lock
+    echo "[queue] enqueue: feature-list.json 업데이트 실패" >&2; exit 1
+  fi
+  mv "$tmp_features" "$FEATURES"
+
+  local deps unmet
+  deps=$(echo "$feat_json" | jq -c '.depends_on // []')
+  unmet=$(jq --argjson d "$deps" '
+    ($d - (.queue.passed // [])) | length
+  ' "$QUEUE" 2>/dev/null || echo 0)
+
+  local tmp_queue="${QUEUE}.tmp.$$"
+  if [ "${unmet:-0}" -gt 0 ]; then
+    jq --arg id "$fid" --argjson deps "$deps" '.queue.blocked[$id] = $deps' "$QUEUE" > "$tmp_queue" 2>/dev/null
+  else
+    jq --arg id "$fid" '.queue.ready += [$id]' "$QUEUE" > "$tmp_queue" 2>/dev/null
+  fi
+  if [ ! -s "$tmp_queue" ]; then
+    rm -f "$tmp_queue"; release_queue_lock
+    echo "[queue] enqueue: feature-queue.json 업데이트 실패" >&2; exit 1
+  fi
+  mv "$tmp_queue" "$QUEUE"
+
+  release_queue_lock
+
+  if [ "${unmet:-0}" -gt 0 ]; then
+    echo "[queue] enqueue: $fid → blocked (unmet deps: ${unmet})"
+  else
+    echo "[queue] enqueue: $fid → ready"
+  fi
+}
+
+# ══════════════════════════════════════════
+# integrity — feature-list ↔ queue divergence 검사.
+# 큐에 있지만 feature-list 에 없는 feature ID 를 출력. 0건이면 종료코드 0.
+# ══════════════════════════════════════════
+cmd_integrity() {
+  if [ ! -f "$FEATURES" ] || [ ! -f "$QUEUE" ]; then
+    echo "[integrity] feature-list 또는 feature-queue 없음"
+    exit 0
+  fi
+  local orphans
+  orphans=$(jq -r --slurpfile q "$QUEUE" '
+    ([.features[].id]) as $fl |
+    (($q[0].queue.ready // []) +
+     ($q[0].queue.passed // []) +
+     (($q[0].queue.failed // []) | if type == "object" then keys else . end) +
+     (($q[0].queue.in_progress // {}) | keys) +
+     (($q[0].queue.blocked // {}) | keys)) as $qids |
+    ($qids - $fl) | unique | .[]
+  ' "$FEATURES" 2>/dev/null)
+
+  if [ -z "$orphans" ]; then
+    echo "[integrity] OK — feature-list ↔ queue 동기화됨"
+    exit 0
+  fi
+  echo "[integrity] ⚠ feature-list 에 없는 queue-only feature 발견:"
+  echo "$orphans" | sed 's/^/  - /'
+  echo "[integrity] 복구 방법:"
+  echo "  1) Planner 가 해당 feature 를 feature-list.json 에 sprint 지정해서 추가하거나"
+  echo "  2) bash scripts/harness-queue-manager.sh enqueue <feature.json>  로 canonical path 사용"
+  exit 1
+}
+
 cmd_hold_status() {
   if [ ! -f "$CHECKPOINT" ]; then
     echo '{"held":false}'
@@ -565,8 +685,10 @@ case "$CMD" in
   hold)           cmd_hold "$@" ;;
   resume-probe)   cmd_resume_probe ;;
   hold-status)    cmd_hold_status ;;
+  enqueue)        cmd_enqueue "$@" ;;
+  integrity)      cmd_integrity ;;
   *)
-    echo "Usage: harness-queue-manager.sh <init|dequeue|auto-dispatch|idle-slots|pass|fail|requeue|recover|next-sprint|update_phase|status|hold|resume-probe|hold-status> [args]"
+    echo "Usage: harness-queue-manager.sh <init|dequeue|auto-dispatch|idle-slots|pass|fail|requeue|recover|next-sprint|update_phase|status|hold|resume-probe|hold-status|enqueue|integrity> [args]"
     exit 1
     ;;
 esac