@walwal-harness/cli 3.3.2 → 3.5.0

package/assets/templates/CONVENTIONS.md

@@ -0,0 +1,61 @@
+# CONVENTIONS.md — Project Conventions
+
+> 이 파일은 프로젝트의 코딩 컨벤션, 선호 패턴, 금지 패턴을 자유 형식으로 정의합니다.
+> 모든 에이전트는 세션 시작 시 이 파일을 읽고 규칙을 적용합니다.
+> 
+> **진실의 원천**: 이 파일이 유일한 컨벤션 정의 소스입니다.
+> Gotcha나 AGENTS.md에 복사하지 마세요 — 에이전트가 직접 이 파일을 참조합니다.
+
+## Architecture
+
+<!-- 아키텍처 수준의 규칙을 여기에 작성하세요 -->
+<!-- 예시:
+- 서비스 간 직접 DB 접근 금지 — 반드시 API 또는 메시지 패턴 사용
+- 모노리스보다 모듈러 아키텍처 선호
+-->
+
+## Code Style
+
+<!-- 코드 스타일 규칙을 여기에 작성하세요 -->
+<!-- 예시:
+- any 타입 사용 금지
+- console.log 대신 structured logger 사용
+- 함수는 30줄 이내, 파일은 300줄 이내
+-->
+
+## Preferred Patterns
+
+<!-- 선호하는 라이브러리, 패턴, 접근 방식 -->
+<!-- 예시:
+- 상태관리: Zustand
+- API 호출: TanStack Query
+- 폼 처리: React Hook Form + Zod
+-->
+
+## Avoid
+
+<!-- 사용을 피해야 하는 패턴, 라이브러리, 접근 방식 -->
+<!-- 예시:
+- CSS-in-JS (styled-components, emotion)
+- Class components
+- Redux (Zustand으로 대체)
+-->
+
+## Testing
+
+<!-- 테스트 관련 규칙 -->
+<!-- 예시:
+- E2E 테스트는 핵심 사용자 플로우만
+- 단위 테스트 커버리지 80% 이상
+- mock 최소화, 실제 DB 사용 선호
+-->
+
+## Naming
+
+<!-- 네이밍 컨벤션 -->
+<!-- 예시:
+- 컴포넌트: PascalCase
+- 변수/함수: camelCase
+- 파일: kebab-case
+- DB 테이블: snake_case
+-->

package/assets/templates/HARNESS.md

@@ -7,6 +7,7 @@
 ## 디렉토리 구조
 
 ```
+CONVENTIONS.md                    # 프로젝트 컨벤션 (사용자 작성, 에이전트 읽기 전용)
 .harness/
 ├── HARNESS.md                  # 이 파일
 ├── config.json                 # 하네스 설정
@@ -142,8 +143,39 @@ pending → draft → reviewed → approved
 | 파일 | 역할 |
 |------|------|
 | `.harness/progress.json` | 기계 판독 상태 (현재 에이전트, 파이프라인, 실패 정보) |
-| `.harness/progress.log` | 사람 판독 히스토리 (append-only) |
-| `.harness/handoff.json` | 세션 전환 문서 (prompt, model, thinking_mode, artifacts, regression) |
+| `.harness/progress.log` | 사람 판독 히스토리 (append-only, 전체) |
+| `.harness/handoff.json` | 세션 전환 문서 (prompt, model, thinking_mode, artifacts) |
+| `.harness/actions/audit.log` | Sprint cycle 단위 실행 추적 (Planner→Eval 통과) |
+
+### Audit Log
+
+1 sprint cycle(Planner/Dispatcher 시작 → Eval 통과) 단위의 상세 실행 추적입니다.
+
+```
+# 예시:
+TIMESTAMP            | AGENT          | ACTION   | STATUS   | TARGET                         | DETAIL
+2026-04-09T14:30:00Z | planner        | plan     | start    | plan.md                        | Sprint 1 설계 시작
+2026-04-09T14:35:00Z | planner        | plan     | complete | api-contract.json              | 3 endpoints, 2 services
+2026-04-09T14:35:01Z | planner        | handoff  | complete | →gen-backend                   |
+2026-04-09T14:36:00Z | system         | gate     | pass     | pre-eval                       | gen-backend
+2026-04-09T14:40:00Z | gen-backend    | develop  | start    | apps/service-user/             | User CRUD 구현
+2026-04-09T14:50:00Z | gen-backend    | develop  | complete | apps/service-user/             | 4 endpoints
+2026-04-09T14:50:01Z | gen-backend    | handoff  | complete | →eval-functional               |
+2026-04-09T14:55:00Z | eval-func      | review   | start    | POST /api/auth/register        | AC-001~003 검증
+2026-04-09T14:58:00Z | eval-func      | review   | fail     | POST /api/auth/register        | 409→400 contract 불일치
+2026-04-09T14:58:01Z | eval-func      | handoff  | complete | →gen-backend                   | Re-Generate
+```
+
+**라이프사이클**: 새 Planner/Dispatcher 사이클 시작 시 이전 로그는 archive로 이동, 새 로그 시작.
+
+**에이전트 기록 의무**: 모든 에이전트는 세션 중 주요 작업의 시작/완료를 audit에 기록해야 합니다.
+
+```bash
+# 에이전트 스킬에서 호출:
+source scripts/lib/harness-audit.sh && init_audit .
+audit_log "gen-backend" "develop" "start" "apps/service-user/" "User CRUD 구현"
+audit_log "gen-backend" "develop" "complete" "apps/service-user/" "4 endpoints 완료"
+```
 
 ### 실행 방법
 
@@ -190,7 +222,7 @@ jq . .harness/progress.json         # 현재 상태 확인
 
 모든 에이전트 스킬에 내장된 프로토콜:
 
-- **On Start**: `progress.json` 읽기 → `agent_status: "running"` 설정 → `handoff.json` 참조
+- **On Start**: `progress.json` 읽기 → `agent_status: "running"` 설정 → `handoff.json` 참조 → `CONVENTIONS.md` 읽기 (존재 시)
 - **On Complete**: `progress.json` 업데이트 → 아티팩트 상태 갱신 → `next_agent` 계산 → **STOP**
 - **On Fail** (Evaluator): `failure` 정보 기록 → `retry_target` 설정 → **STOP**
 - **On Transition**: 파일 소유권 검증 → Pre-Eval Gate (해당 시) → 아티팩트 선행조건 검증

package/assets/templates/config.json

@@ -333,9 +333,34 @@
     "actions": ".harness/actions",
     "archive": ".harness/archive",
     "gotchas": ".harness/gotchas",
+    "conventions": "CONVENTIONS.md",
     "progress_state": ".harness/progress.json",
     "progress_log": ".harness/progress.log"
   },
+  "audit": {
+    "comment": "Audit log — 1 sprint cycle 단위의 실행 추적. Planner/Dispatcher 시작 시 리셋.",
+    "file": ".harness/actions/audit.log",
+    "lifecycle": "planner_to_eval_pass",
+    "reset_on": ["planner", "dispatcher"],
+    "archive_previous": true,
+    "format": "TIMESTAMP | AGENT | ACTION | STATUS | TARGET | DETAIL",
+    "actions": {
+      "develop": "코드 생성/수정 (Generator)",
+      "review": "검수/평가 (Evaluator)",
+      "handoff": "에이전트 전환",
+      "plan": "설계/계획 (Planner)",
+      "gate": "자동 게이트 체크 (system)",
+      "escalate": "에스컬레이션 (system)"
+    },
+    "statuses": ["start", "complete", "fail", "pass", "skip", "warn"]
+  },
+  "conventions": {
+    "comment": "CONVENTIONS.md — 사용자가 자유 형식으로 작성하는 프로젝트 컨벤션. 모든 에이전트가 세션 시작 시 직접 읽음. Gotcha/AGENTS.md에 복사하지 않음.",
+    "file": "CONVENTIONS.md",
+    "read_by": "all_agents",
+    "write_by": "user_only",
+    "read_timing": "session_start"
+  },
   "recommended_skills": {
     "comment": "Claude Code에 설치하면 하네스 품질이 향상되는 외부 스킬 목록",
     "vercel": {

package/bin/init.js

@@ -148,6 +148,14 @@ function scaffoldHarness() {
     copyFile(memorySrc, memoryDest);
   }
 
+  // Copy CONVENTIONS.md to project root
+  const conventionsSrc = path.join(PKG_ROOT, 'assets', 'templates', 'CONVENTIONS.md');
+  const conventionsDest = path.join(PROJECT_ROOT, 'CONVENTIONS.md');
+  if (fs.existsSync(conventionsSrc) && (!fileExists(conventionsDest) || isForce)) {
+    copyFile(conventionsSrc, conventionsDest);
+    log('CONVENTIONS.md created — edit to define your project conventions');
+  }
+
   // Create progress.log
   const progressLog = path.join(HARNESS_DIR, 'progress.log');
   if (!fileExists(progressLog) || isForce) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@walwal-harness/cli",
-  "version": "3.3.2",
+  "version": "3.5.0",
   "description": "Production harness for AI agent engineering — Planner, Generator(BE/FE), Evaluator(Func/Visual), optional Brainstormer (requirements refinement). Supports React and Flutter FE stacks.",
   "bin": {
     "walwal-harness": "bin/init.js"

package/scripts/harness-next.sh

@@ -7,6 +7,7 @@ set -e
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 source "$SCRIPT_DIR/lib/harness-render-progress.sh"
 source "$SCRIPT_DIR/lib/harness-guardrail.sh"
+source "$SCRIPT_DIR/lib/harness-audit.sh"
 
 # ─────────────────────────────────────────
 # Resolve project root
@@ -24,6 +25,9 @@ HANDOFF="$PROJECT_ROOT/.harness/handoff.json"
 
 check_jq || exit 1
 
+# Initialize audit log
+init_audit "$PROJECT_ROOT"
+
 if [ ! -f "$PROGRESS" ]; then
   echo "[harness] ERROR: progress.json not found" >&2
   echo "  Run 'npx walwal-harness --force' to reinitialize." >&2
@@ -277,15 +281,25 @@ verify_artifact_prerequisites() {
 # Runtime Guardrail — 파일 소유권 검증
 # ─────────────────────────────────────────
 if [ "$agent_status" = "completed" ]; then
-  verify_file_ownership "$PROJECT_ROOT" || true
+  audit_log "$current_agent" "develop" "complete" "" "agent completed"
+  verify_file_ownership "$PROJECT_ROOT" || audit_gate "file-ownership" "warn" "boundary violation detected"
 fi
 
 # ─────────────────────────────────────────
 # Run Pre-Eval Gate (if applicable)
 # ─────────────────────────────────────────
 if [ "$agent_status" = "completed" ]; then
-  run_pre_eval_gate "$next_agent" || true
-  verify_artifact_prerequisites "$next_agent" || true
+  audit_gate "pre-eval" "start" "$next_agent"
+  if run_pre_eval_gate "$next_agent"; then
+    audit_gate "pre-eval" "pass" "$next_agent"
+  else
+    audit_gate "pre-eval" "fail" "rerouted to $current_agent"
+  fi
+  if verify_artifact_prerequisites "$next_agent"; then
+    audit_gate "artifact-prereq" "pass" "$next_agent"
+  else
+    audit_gate "artifact-prereq" "fail" "$next_agent"
+  fi
 fi
 
 # ─────────────────────────────────────────
@@ -303,6 +317,7 @@ if [ "$next_agent" != "null" ] && [ "$next_agent" != "archive" ] && [ "$agent_st
   escalate_after=$(jq -r '.flow.escalate_to_planner_after // 3' "$CONFIG" 2>/dev/null || echo 3)
   if [ "$retry_count" -ge "$escalate_after" ] && [ "$sprint_status" = "failed" ] && [ "$next_agent" != "planner" ]; then
     echo "  ⚠ Escalation: ${retry_count}회 실패 — Planner에게 scope 축소/접근 변경 요청"
+    audit_log "system" "escalate" "start" "→planner" "retry ${retry_count}회 초과"
     next_agent="planner"
     jq --arg msg "Escalated after ${retry_count} failures. Planner must review scope or approach." \
        '.next_agent = "planner" |
@@ -442,7 +457,10 @@ if [ "$next_agent" != "null" ] && [ "$next_agent" != "archive" ] && [ "$agent_st
       timestamp: $timestamp
     }' > "$HANDOFF"
 
+  audit_handoff "${current_agent:-dispatcher}" "$next_agent" "complete"
+
 elif [ "$next_agent" = "archive" ]; then
+  audit_log "system" "archive" "start" "sprint-${sprint_num}" "sprint cycle complete"
   jq -n \
     --arg from "${current_agent:-evaluator}" \
     --argjson sprint "$sprint_num" \

package/scripts/harness-session-start.sh

@@ -1,17 +1,17 @@
 #!/bin/bash
 # harness-session-start.sh — SessionStart 훅
 # 새 세션 시작 시 자동으로:
-#   1) 이전 에이전트가 completed이면 harness-next.sh를 실행하여 게이트 체크 + handoff 생성
-#   2) handoff.json이 있으면 다음 에이전트 안내
-#   3) statusline이 상시 상태를 표시하므로 여기서는 핵심 안내만 출력
-#
-# 사용자가 수동으로 harness-next.sh를 실행할 필요가 없도록 자동화.
+#   1) 이전 에이전트가 completed이면 harness-next.sh 실행 (게이트 + handoff)
+#   2) Planner/Dispatcher 사이클이면 audit 리셋
+#   3) 다음 에이전트 안내 출력
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 LIB="$SCRIPT_DIR/lib/harness-render-progress.sh"
+AUDIT_LIB="$SCRIPT_DIR/lib/harness-audit.sh"
 
 if [ ! -f "$LIB" ]; then exit 0; fi
 source "$LIB"
+[ -f "$AUDIT_LIB" ] && source "$AUDIT_LIB"
 command -v jq &>/dev/null || exit 0
 
 PROJECT_ROOT="$(resolve_harness_root "." 2>/dev/null)" || exit 0
@@ -21,6 +21,7 @@ HANDOFF="$PROJECT_ROOT/.harness/handoff.json"
 [ -f "$PROGRESS" ] || exit 0
 
 sprint_status=$(jq -r '.sprint.status // "init"' "$PROGRESS" 2>/dev/null)
+sprint_num=$(jq -r '.sprint.number // 0' "$PROGRESS" 2>/dev/null)
 current_agent=$(jq -r '.current_agent // "none"' "$PROGRESS" 2>/dev/null)
 next_agent=$(jq -r '.next_agent // "none"' "$PROGRESS" 2>/dev/null)
 agent_status=$(jq -r '.agent_status // "pending"' "$PROGRESS" 2>/dev/null)
@@ -34,14 +35,21 @@ if [ "$sprint_status" = "init" ]; then
 fi
 
 # ─────────────────────────────────────────
-# 이전 에이전트가 completed → 자동으로 harness-next 실행
-# (게이트 체크, 아티팩트 검증, handoff.json 생성)
+# Audit lifecycle: Planner/Dispatcher 시작 시 리셋
+# ─────────────────────────────────────────
+init_audit "$PROJECT_ROOT"
+if [ "$next_agent" = "planner" ] || [ "$next_agent" = "dispatcher" ]; then
+  # 새 사이클 — 이전 audit을 archive로 이동하고 새로 시작
+  reset_audit "$PROJECT_ROOT" "$sprint_num"
+  audit_log "system" "cycle" "start" "sprint-${sprint_num}" "new plan/dispatch cycle"
+fi
+
+# ─────────────────────────────────────────
+# 이전 에이전트가 completed/failed → 자동 전환
 # ─────────────────────────────────────────
 if [ "$agent_status" = "completed" ] || [ "$agent_status" = "failed" ]; then
-  # harness-next.sh를 백그라운드로 실행하면 안 됨 — 결과가 필요
   bash "$SCRIPT_DIR/harness-next.sh" "$PROJECT_ROOT" 2>/dev/null
 
-  # harness-next.sh가 progress.json과 handoff.json을 업데이트했으므로 다시 읽기
   next_agent=$(jq -r '.next_agent // "none"' "$PROGRESS" 2>/dev/null)
   agent_status=$(jq -r '.agent_status // "pending"' "$PROGRESS" 2>/dev/null)
 fi
@@ -53,7 +61,6 @@ if [ "$agent_status" = "blocked" ]; then
   echo "# Harness BLOCKED — retry limit reached, user intervention required"
 
 elif [ -f "$HANDOFF" ] && [ "$next_agent" != "none" ] && [ "$next_agent" != "null" ]; then
-  # handoff.json에서 모델/모드 정보 읽기
   handoff_model=$(jq -r '.model // "opus"' "$HANDOFF" 2>/dev/null)
   handoff_thinking=$(jq -r '.thinking_mode // empty' "$HANDOFF" 2>/dev/null)
 

package/scripts/lib/harness-audit.sh

@@ -0,0 +1,113 @@
+#!/bin/bash
+# harness-audit.sh — Audit log 헬퍼
+#
+# 라이프사이클: Planner 시작 → Eval 통과 (1 sprint cycle)
+# 새 Planner/Dispatcher 사이클 시작 시 이전 로그는 archive로 이동.
+#
+# 사용법:
+#   source scripts/lib/harness-audit.sh
+#   audit_log "gen-backend" "develop" "start" "apps/service-user/" "User 서비스 CRUD 구현"
+#   audit_log "eval-func"   "review"  "complete" "POST /api/auth" "FAIL: 409→400 contract 불일치"
+#   audit_log "gen-backend" "handoff" "start" "→eval-functional" ""
+
+AUDIT_LOG_FILE=""
+
+# ─────────────────────────────────────────
+# init_audit — audit.log 경로 설정 + 헤더 생성
+# Args: $1 = project root
+# ─────────────────────────────────────────
+init_audit() {
+  local project_root="${1:-.}"
+  AUDIT_LOG_FILE="$project_root/.harness/actions/audit.log"
+
+  # 디렉토리 보장
+  mkdir -p "$(dirname "$AUDIT_LOG_FILE")"
+}
+
+# ─────────────────────────────────────────
+# reset_audit — 새 사이클 시작 시 로그 초기화
+# 이전 로그가 있으면 archive로 이동
+# Args: $1 = project root, $2 = sprint number (optional)
+# ─────────────────────────────────────────
+reset_audit() {
+  local project_root="${1:-.}"
+  local sprint_num="${2:-0}"
+  init_audit "$project_root"
+
+  # 기존 로그가 있으면 archive로 이동
+  if [ -f "$AUDIT_LOG_FILE" ] && [ -s "$AUDIT_LOG_FILE" ]; then
+    local archive_dir="$project_root/.harness/archive"
+    mkdir -p "$archive_dir"
+    local ts
+    ts=$(date +%Y%m%d_%H%M%S)
+    mv "$AUDIT_LOG_FILE" "$archive_dir/audit_s${sprint_num}_${ts}.log"
+  fi
+
+  # 새 로그 헤더
+  cat > "$AUDIT_LOG_FILE" <<HEADER
+# Harness Audit Log
+# Cycle started: $(date -u +%Y-%m-%dT%H:%M:%SZ)
+# Format: TIMESTAMP | AGENT | ACTION | STATUS | TARGET | DETAIL
+#─────────────────────────────────────────────────────────────────────────
+HEADER
+}
+
+# ─────────────────────────────────────────
+# audit_log — 로그 엔트리 추가
+#
+# Args:
+#   $1 = agent     (planner, gen-backend, gen-frontend, eval-func, eval-visual)
+#   $2 = action    (develop, review, handoff, plan, gate)
+#   $3 = status    (start, complete, fail, skip)
+#   $4 = target    (파일 경로, 엔드포인트, 에이전트명 등)
+#   $5 = detail    (설명, 결과 등)
+# ─────────────────────────────────────────
+audit_log() {
+  if [ -z "$AUDIT_LOG_FILE" ] || [ ! -f "$AUDIT_LOG_FILE" ]; then
+    return 0  # audit 미초기화 시 silent pass
+  fi
+
+  local agent="${1:-unknown}"
+  local action="${2:-unknown}"
+  local log_status="${3:-unknown}"
+  local target="${4:-}"
+  local detail="${5:-}"
+  local ts
+  ts=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+  # 고정폭 포맷
+  printf "%-20s | %-14s | %-8s | %-8s | %-30s | %s\n" \
+    "$ts" "$agent" "$action" "$log_status" "$target" "$detail" >> "$AUDIT_LOG_FILE"
+}
+
+# ─────────────────────────────────────────
+# audit_handoff — 핸즈오프 기록 (편의 함수)
+# Args: $1=from_agent, $2=to_agent, $3=status(start|complete)
+# ─────────────────────────────────────────
+audit_handoff() {
+  audit_log "$1" "handoff" "$3" "→${2}" ""
+}
+
+# ─────────────────────────────────────────
+# audit_gate — 게이트 체크 기록 (편의 함수)
+# Args: $1=gate_name, $2=status(pass|fail), $3=detail
+# ─────────────────────────────────────────
+audit_gate() {
+  audit_log "system" "gate" "$2" "$1" "$3"
+}
+
+# ─────────────────────────────────────────
+# render_audit — audit.log를 읽기 좋게 출력
+# Args: $1 = project root (optional)
+# ─────────────────────────────────────────
+render_audit() {
+  local project_root="${1:-.}"
+  local log_file="$project_root/.harness/actions/audit.log"
+
+  if [ ! -f "$log_file" ]; then
+    echo "  (audit log not yet created)"
+    return 0
+  fi
+
+  cat "$log_file"
+}