@walwal-harness/cli 6.0.5 → 6.1.1

package/scripts/init-agents-md.sh

@@ -0,0 +1,337 @@
+#!/bin/bash
+# init-agents-md.sh — scan-result.json을 기반으로 AGENTS.md를 생성/리빌드
+# 기존 CLAUDE.md의 사용자 규칙을 보존하면서 하네스 포맷으로 변환
+set -e
+
+PROJECT_ROOT="${1:-.}"
+SCAN_RESULT="${PROJECT_ROOT}/.harness/actions/scan-result.json"
+export SCAN_RESULT PROJECT_ROOT
+AGENTS_FILE="${PROJECT_ROOT}/AGENTS.md"
+CLAUDE_FILE="${PROJECT_ROOT}/CLAUDE.md"
+BACKUP_DIR="${PROJECT_ROOT}/.harness/archive/pre-harness-backup"
+
+if [ ! -f "$SCAN_RESULT" ]; then
+  echo "ERROR: scan-result.json not found. Run scan-project.sh first."
+  exit 1
+fi
+
+# ─────────────────────────────────────────
+# 1. Python으로 scan-result.json 파싱
+# ─────────────────────────────────────────
+eval "$(python3 << 'PYEOF'
+import json, sys, os
+
+with open(os.environ.get("SCAN_RESULT", ".harness/actions/scan-result.json")) as f:
+    scan = json.load(f)
+
+docs = scan["existing_docs"]
+tech = scan["tech_stack"]
+rec = scan["recommendation"]
+dirs = scan["structure"]["directories"]
+configs = scan["structure"]["config_files"]
+
+print(f'ACTION="{rec["agents_md_action"]}"')
+print(f'PROJECT_TYPE="{rec["project_type"]}"')
+print(f'TECH_BE="{tech["backend"]}"')
+print(f'TECH_FE="{tech["frontend"]}"')
+print(f'TECH_DB="{tech["database"]}"')
+print(f'TECH_MONO="{tech["monorepo"]}"')
+print(f'OPENAPI="{scan["api"]["openapi_spec"]}"')
+print(f'HAS_EXISTING_CLAUDE="{docs["claude_md"]}"')
+print(f'EXISTING_CONTENT={json.dumps(docs["existing_claude_md_content"])}')
+PYEOF
+)"
+
+echo "=== AGENTS.md Initialization ==="
+echo "Action: ${ACTION}"
+echo "Project Type: ${PROJECT_TYPE}"
+echo ""
+
+# ─────────────────────────────────────────
+# 2. 기존 문서 백업
+# ─────────────────────────────────────────
+if [ "$ACTION" = "migrate-claude-to-agents" ] || [ "$ACTION" = "rebuild-with-harness" ]; then
+  mkdir -p "$BACKUP_DIR"
+  TIMESTAMP=$(date +%Y%m%d_%H%M%S)
+
+  if [ -f "$AGENTS_FILE" ] && [ ! -L "$AGENTS_FILE" ]; then
+    cp "$AGENTS_FILE" "${BACKUP_DIR}/AGENTS.md.${TIMESTAMP}.bak"
+    echo "Backed up: AGENTS.md → ${BACKUP_DIR}/AGENTS.md.${TIMESTAMP}.bak"
+  fi
+
+  if [ -f "$CLAUDE_FILE" ] && [ ! -L "$CLAUDE_FILE" ]; then
+    cp "$CLAUDE_FILE" "${BACKUP_DIR}/CLAUDE.md.${TIMESTAMP}.bak"
+    echo "Backed up: CLAUDE.md → ${BACKUP_DIR}/CLAUDE.md.${TIMESTAMP}.bak"
+  fi
+fi
+
+# ─────────────────────────────────────────
+# 3. IA-MAP 자동 생성
+# ─────────────────────────────────────────
+generate_ia_map() {
+  python3 << 'PYEOF'
+import json, os
+
+with open(os.environ.get("SCAN_RESULT", ".harness/actions/scan-result.json")) as f:
+    scan = json.load(f)
+
+dirs = scan["structure"]["directories"]
+tech = scan["tech_stack"]
+
+# 경로별 태그/설명 추론 규칙
+tag_rules = {
+    # Backend patterns
+    "apps/gateway": ("[BE]", "API Gateway", "Generator-Backend"),
+    "apps/service": ("[BE]", "Microservice", "Generator-Backend"),
+    "src/controllers": ("[BE]", "API Controllers", "Generator-Backend"),
+    "src/services": ("[BE]", "Business Logic", "Generator-Backend"),
+    "src/models": ("[BE]", "Data Models", "Generator-Backend"),
+    "src/entities": ("[BE]", "DB Entities", "Generator-Backend"),
+    "src/modules": ("[BE]", "NestJS Modules", "Generator-Backend"),
+    "src/guards": ("[BE]", "Auth Guards", "Generator-Backend"),
+    "src/pipes": ("[BE]", "Validation Pipes", "Generator-Backend"),
+    "src/interceptors": ("[BE]", "Interceptors", "Generator-Backend"),
+    "src/filters": ("[BE]", "Exception Filters", "Generator-Backend"),
+    "routers": ("[BE]", "API Routers", "Generator-Backend"),
+    "routes": ("[BE]", "API Routes", "Generator-Backend"),
+    "middleware": ("[BE]", "Middleware", "Generator-Backend"),
+    "migrations": ("[BE]", "DB Migrations", "Generator-Backend"),
+
+    # Frontend patterns
+    "apps/web": ("[FE]", "Frontend App", "Generator-Frontend"),
+    "src/components": ("[FE]", "UI Components", "Generator-Frontend"),
+    "src/pages": ("[FE]", "Page Routes", "Generator-Frontend"),
+    "src/app": ("[FE]", "App Router", "Generator-Frontend"),
+    "src/hooks": ("[FE]", "Custom Hooks", "Generator-Frontend"),
+    "src/stores": ("[FE]", "State Management", "Generator-Frontend"),
+    "src/styles": ("[FE]", "Stylesheets", "Generator-Frontend"),
+    "src/api": ("[FE]", "API Client Layer", "Generator-Frontend"),
+    "src/lib": ("[FE]", "Utility Library", "Generator-Frontend"),
+    "public": ("[FE]", "Static Assets", "Generator-Frontend"),
+
+    # Shared / Libs
+    "libs/shared": ("[BE]", "Shared Libraries", "Generator-Backend"),
+    "libs/database": ("[BE]", "Database Module", "Generator-Backend"),
+    "libs/common": ("[BE]", "Common Utilities", "Generator-Backend"),
+
+    # Infra
+    "docker": ("[INFRA]", "Docker Configuration", "Planner"),
+    ".github": ("[INFRA]", "CI/CD Workflows", "Planner"),
+    "deploy": ("[INFRA]", "Deployment Scripts", "Planner"),
+    "terraform": ("[INFRA]", "Infrastructure as Code", "Planner"),
+    "k8s": ("[INFRA]", "Kubernetes Manifests", "Planner"),
+
+    # Harness
+    ".harness": ("[HARNESS]", "Harness System", "Planner"),
+
+    # Tests
+    "test": ("[TEST]", "Test Suite", "Evaluator"),
+    "tests": ("[TEST]", "Test Suite", "Evaluator"),
+    "e2e": ("[TEST]", "E2E Tests", "Evaluator"),
+    "__tests__": ("[TEST]", "Unit Tests", "Evaluator"),
+
+    # Native app patterns (Swift / Kotlin / Rust 등)
+    "Sources": ("[FE]", "Native Source Root", "Generator-Frontend"),
+    "Tests": ("[TEST]", "Native Test Suite", "Evaluator"),
+    "Resources": ("[FE]", "Native Resources", "Generator-Frontend"),
+    "android": ("[FE]", "Android Host", "Generator-Frontend"),
+    "ios": ("[FE]", "iOS Host", "Generator-Frontend"),
+    "macos": ("[FE]", "macOS Host", "Generator-Frontend"),
+    "Shared": ("[FE]", "Cross-platform Shared", "Generator-Frontend"),
+}
+
+# 디렉토리를 분석
+ia_lines = []
+for d in sorted(dirs):
+    if d == "." or not d:
+        continue
+
+    matched = False
+    for pattern, (tag, desc, owner) in tag_rules.items():
+        if pattern in d:
+            depth = d.count("/")
+            indent = "│   " * depth
+            name = d.split("/")[-1] + "/"
+            ia_lines.append(f"{indent}├── {name:<25} # {tag} {desc:<30} → {owner}")
+            matched = True
+            break
+
+    if not matched:
+        depth = d.count("/")
+        if depth <= 1:  # 1depth만 미분류 표시
+            indent = "│   " * depth
+            name = d.split("/")[-1] + "/"
+            ia_lines.append(f"{indent}├── {name:<25} # [?] (Planner가 분류 필요)       → TBD")
+
+for line in ia_lines:
+    print(line)
+PYEOF
+}
+
+IA_MAP=$(generate_ia_map)
+
+# ─────────────────────────────────────────
+# 4. 기존 사용자 규칙 추출 (CLAUDE.md에서)
+# ─────────────────────────────────────────
+extract_user_rules() {
+  if [ "$HAS_EXISTING_CLAUDE" = "exists" ]; then
+    python3 << 'PYEOF'
+import json, os
+
+with open(os.environ.get("SCAN_RESULT", ".harness/actions/scan-result.json")) as f:
+    scan = json.load(f)
+
+content = scan["existing_docs"]["existing_claude_md_content"]
+
+if not content or content.strip() == "":
+    print("(기존 규칙 없음)")
+else:
+    # 사용자 정의 규칙 영역만 추출 (harness 관련 제외)
+    lines = content.split("\n")
+    user_section = []
+    skip = False
+    for line in lines:
+        # harness가 생성한 섹션은 제외
+        if any(kw in line.lower() for kw in ["ia-map", "ia map", "harness", "## tech stack"]):
+            skip = True
+        elif line.startswith("## ") and skip:
+            skip = False
+
+        if not skip:
+            user_section.append(line)
+
+    result = "\n".join(user_section).strip()
+    if result:
+        print(result)
+    else:
+        print("(기존 규칙 없음)")
+PYEOF
+  else
+    echo "(기존 규칙 없음)"
+  fi
+}
+
+USER_RULES=$(extract_user_rules)
+
+# ─────────────────────────────────────────
+# 5. AGENTS.md 생성
+# ─────────────────────────────────────────
+cat > "$AGENTS_FILE" << AGENTSEOF
+# AGENTS.md — Project Context for AI Agents
+
+> 이 파일은 모든 AI 에이전트(Claude, Cursor, Copilot, Windsurf 등)의 공통 진입점입니다.
+> CLAUDE.md는 이 파일의 심볼릭 링크입니다.
+> Generated by walwal-harness ($(date +%Y-%m-%d))
+
+## Project
+
+- **Name**: (Planner가 설정)
+- **Description**: (Planner가 설정)
+- **Phase**: INIT
+- **Type**: ${PROJECT_TYPE}
+- **Harness**: \`.harness/HARNESS.md\` 참조
+
+## Tech Stack (Auto-detected)
+
+- Backend: ${TECH_BE}
+- Frontend: ${TECH_FE}
+- Database: ${TECH_DB}
+- Monorepo: ${TECH_MONO}
+- OpenAPI: ${OPENAPI}
+
+## IA-MAP (Information Architecture)
+
+> 자동 스캔으로 생성됨. Planner가 검토 후 확정해야 합니다.
+> \`[?]\` 태그는 Planner가 분류해야 하는 미확인 경로입니다.
+
+\`\`\`
+/
+${IA_MAP}
+├── AGENTS.md                 # [META] 프로젝트 컨텍스트           → Planner
+├── CLAUDE.md                 # [META] → AGENTS.md 심볼릭 링크
+└── .harness/                 # [HARNESS] 하네스 시스템             → Planner
+\`\`\`
+
+### IA-MAP 범례
+
+| 태그 | 의미 | 소유 에이전트 |
+|------|------|--------------|
+| \`[BE]\` | Backend 영역 | Generator-Backend |
+| \`[FE]\` | Frontend 영역 | Generator-Frontend |
+| \`[HARNESS]\` | 하네스 시스템 | Planner / Evaluator |
+| \`[META]\` | 프로젝트 메타 문서 | Planner |
+| \`[INFRA]\` | 인프라/배포 설정 | Planner |
+| \`[TEST]\` | 테스트 코드 | Evaluator / Generator |
+| \`[?]\` | 미분류 (Planner 확인 필요) | TBD |
+
+## Preserved Rules (기존 프로젝트에서 이관)
+
+${USER_RULES}
+
+## Rules (모든 에이전트 공통)
+
+### 읽기/쓰기 권한
+
+| 파일 | 읽기 | 쓰기 |
+|------|------|------|
+| AGENTS.md | 전체 | Planner만 |
+| .harness/actions/api-contract.json | 전체 | Planner만 |
+| .harness/actions/feature-list.json | 전체 | passes: Generator, 나머지: Planner |
+| .harness/progress.json | 전체 | 전체 (Session Boundary Protocol에 따라 업데이트) |
+| \`[BE]\` 소유 경로 | 전체 | Generator-Backend만 |
+| \`[FE]\` 소유 경로 | 전체 | Generator-Frontend만 |
+| .harness/archive/ | 전체 | 쓰기 금지 (불변) |
+
+### 변경 요청 프로토콜
+
+AGENTS.md 또는 api-contract.json 변경이 필요할 때:
+1. sprint-contract.md에 \`## Change Request\` 섹션 추가
+2. Planner가 다음 스프린트 전환 시 반영 여부 결정
+
+### 금지 사항
+
+- AGENTS.md를 Planner 외 에이전트가 수정
+- 서비스 간 직접 DB 접근
+- 테스트 삭제/약화
+- archive/ 내 파일 수정
+- 프로젝트를 조기 "완료" 선언
+
+## Harness Quick Reference
+
+| 명령 | 설명 |
+|------|------|
+| \`bash scripts/scan-project.sh\` | 프로젝트 구조 재스캔 |
+| \`.harness/progress.json\` | 현재 진행 상태 (기계 판독) |
+| \`.harness/actions/\` | 활성 스프린트 문서 |
+| \`.harness/HARNESS.md\` | 하네스 상세 가이드 |
+AGENTSEOF
+
+echo ""
+echo "=== AGENTS.md Generated ==="
+echo "Path: ${AGENTS_FILE}"
+
+# ─────────────────────────────────────────
+# 6. CLAUDE.md 심볼릭 링크
+# ─────────────────────────────────────────
+if [ -f "$CLAUDE_FILE" ] && [ ! -L "$CLAUDE_FILE" ]; then
+  echo ""
+  echo "WARNING: CLAUDE.md가 일반 파일로 존재합니다."
+  echo "기존 내용은 AGENTS.md의 'Preserved Rules' 섹션에 이관되었습니다."
+  echo "백업: ${BACKUP_DIR}/"
+  rm "$CLAUDE_FILE"
+fi
+
+if [ ! -L "$CLAUDE_FILE" ]; then
+  ln -sf AGENTS.md "$CLAUDE_FILE"
+  echo "Created symlink: CLAUDE.md → AGENTS.md"
+else
+  echo "Symlink already exists: CLAUDE.md → AGENTS.md"
+fi
+
+echo ""
+echo "=== Initialization Complete ==="
+echo ""
+echo "Next steps:"
+echo "  1. AGENTS.md의 [?] 태그를 확인하고 Planner에게 분류를 요청하세요"
+echo "  2. 'Preserved Rules' 섹션에서 불필요한 규칙을 정리하세요"
+echo "  3. '하네스 엔지니어링 시작'으로 Dispatcher를 실행하세요"

package/scripts/init-ref-docs.sh

@@ -0,0 +1,262 @@
+#!/bin/bash
+# init-ref-docs.sh — 감지된 스택에 따라 .harness/ref/<role>-<stack>.md 를 준비한다.
+#
+# bash 혼자서는 Claude 의 WebSearch/WebFetch 를 호출할 수 없으므로 이 스크립트는:
+#   1. scan-result.json 에서 감지된 스택 목록을 계산
+#   2. --placeholder 모드: 최소 frontmatter + TODO 본문을 저장 (AC 검증용 · 파이프라인 unblock 용)
+#   3. --claude-prompt 모드: Claude 세션이 실제 WebSearch + WebFetch + synthesis 로 채울 수 있도록 프롬프트 템플릿을 stdout 출력
+#   4. --register 모드: Claude 가 실제 본문을 작성한 뒤 호출해 .generated.json 에 sources / generated_at 을 등록
+#
+# 사용 예:
+#   bash scripts/init-ref-docs.sh --dry-run .
+#   bash scripts/init-ref-docs.sh --yes --placeholder --stack swift --role fe .
+#   bash scripts/init-ref-docs.sh --claude-prompt --stack swift --role fe .
+#   bash scripts/init-ref-docs.sh --register --stack swift --role fe --sources "https://a,https://b" .
+set -e
+
+# ───── 옵션 파싱 ─────
+MODE="interactive"    # interactive | dry-run | placeholder | claude-prompt | register
+YES=false
+REFRESH=false
+STACK=""
+ROLE=""
+SOURCES=""
+PROJECT_ROOT="."
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --dry-run)        MODE="dry-run"; shift ;;
+    --placeholder)    MODE="placeholder"; shift ;;
+    --claude-prompt)  MODE="claude-prompt"; shift ;;
+    --register)       MODE="register"; shift ;;
+    --yes)            YES=true; shift ;;
+    --refresh)        REFRESH=true; shift ;;
+    --stack)          STACK="$2"; shift 2 ;;
+    --role)           ROLE="$2"; shift 2 ;;
+    --sources)        SOURCES="$2"; shift 2 ;;
+    -h|--help)
+      sed -n '2,16p' "$0" | sed 's/^# //; s/^#//'
+      exit 0 ;;
+    *)                PROJECT_ROOT="$1"; shift ;;
+  esac
+done
+
+SCAN="${PROJECT_ROOT}/.harness/actions/scan-result.json"
+REF_DIR="${PROJECT_ROOT}/.harness/ref"
+META="${REF_DIR}/.generated.json"
+ARCHIVE_DIR="${PROJECT_ROOT}/.harness/archive"
+mkdir -p "$REF_DIR" "$ARCHIVE_DIR"
+[ -f "$META" ] || echo "{}" > "$META"
+
+# ───── 감지된 스택 목록 ─────
+detect_stacks() {
+  if [ ! -f "$SCAN" ]; then
+    echo "ERROR: scan-result.json 이 없습니다. 먼저 bash scripts/scan-project.sh ${PROJECT_ROOT} 실행하세요." >&2
+    exit 1
+  fi
+  local fe be native
+  fe=$(jq -r '.tech_stack.frontend' "$SCAN")
+  be=$(jq -r '.tech_stack.backend' "$SCAN")
+  native=$(jq -r '.tech_stack.is_native_app // false' "$SCAN")
+
+  # 네이티브 앱은 fe 만 기록 (be 는 null)
+  if [ "$fe" != "unknown" ] && [ "$fe" != "null" ]; then
+    echo "fe:$fe"
+  fi
+  if [ "$native" != "true" ] && [ "$be" != "unknown" ] && [ "$be" != "null" ]; then
+    echo "be:$be"
+  fi
+}
+
+# ───── placeholder 본문 ─────
+write_placeholder() {
+  local role="$1" stack="$2" path="$3"
+  local ts
+  ts=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+  cat > "$path" <<REF
+---
+docmeta:
+  id: ref-${role}-${stack}
+  stack: ${stack}
+  role: ${role}
+  language: ${stack}
+  generated_at: ${ts}
+  generator: init-ref-docs.sh (placeholder)
+  sources: []
+  version: 0
+runner:
+  dev_command: null
+  start_command: null
+  install_command: null
+paths:
+  source_roots: []
+  test_roots: []
+  config_files: []
+api:
+  base_url: null
+  gateway: null
+validation:
+  pre_eval_gate: []
+  functional_tests: []
+  visual:
+    enabled: false
+    reason: "placeholder — not yet filled by Claude"
+    manual_check: "bash init.sh refresh-ref ${role} ${stack} 실행 후 Claude 세션에서 WebSearch + WebFetch 로 채우기"
+  anti_pattern_rules: []
+---
+
+# Ref — ${stack} (${role})
+
+> **Status**: PLACEHOLDER — Claude 가 WebSearch + WebFetch 로 채워야 함.
+> 실행: bash scripts/init-ref-docs.sh --claude-prompt --stack ${stack} --role ${role}
+
+## 1. Runner
+TODO
+
+## 2. Paths / Source Layout
+TODO
+
+## 3. Best Practices
+TODO
+
+## 4. Anti-Patterns (→ gotchas 시드 후보)
+TODO
+REF
+}
+
+# ───── Claude 용 프롬프트 ─────
+# React 계열 스택 (react / nextjs / vite-react) 일 때는
+# skills/generator-frontend/references/_web-react-legacy/ 의 4개 문서를
+# 로컬 seed 로 프롬프트에 포함시킨다. 이 seed 는 새 ref-docs 작성 시
+# "기존 웹 React 가이드" 참조용이며 WebSearch 결과와 병합된다.
+LEGACY_SEED_DIR="$(dirname "$0")/../skills/generator-frontend/references/_web-react-legacy"
+emit_claude_prompt() {
+  local role="$1" stack="$2" path="$3"
+  local legacy_hint=""
+  if [ "$role" = "fe" ] && [ -d "$LEGACY_SEED_DIR" ]; then
+    case "$stack" in
+      react|nextjs|vite-react|nuxt|vue|svelte|angular|*web*)
+        legacy_hint="
+Local seed (병합 대상 · 이미 검증된 웹/React best practice):
+$(ls "$LEGACY_SEED_DIR" 2>/dev/null | sed 's|^|  - '"$LEGACY_SEED_DIR"'/|')
+"
+        ;;
+    esac
+  fi
+  cat <<PROMPT
+───────────────────────────────────────────────
+Claude 세션에 아래 프롬프트를 전달하세요
+(또는 현재 세션이라면 그대로 실행):
+───────────────────────────────────────────────
+
+목표: ${path} 를 생성한다.
+
+1. WebSearch 로 다음 쿼리 실행: "${stack} best practices 2025 site:docs.*"
+2. 상위 3개 공식 문서 URL 을 WebFetch 로 가져온다.
+3. 결과를 종합해 다음 스키마로 YAML frontmatter + 본문을 작성한다:
+   - docmeta: { id, stack, role, language, generated_at, generator, sources, version }
+   - runner: { dev_command, start_command, install_command }
+   - paths: { source_roots, test_roots, config_files }
+   - api: { base_url, gateway }
+   - validation:
+       pre_eval_gate: [...]
+       functional_tests: [...]
+       visual: { enabled, reason, manual_check }
+       anti_pattern_rules: [{ id, pattern_type: "grep"|"lint_tool", pattern|tool+args, paths, severity }]
+4. 본문에는 Runner / Paths / Best Practices / Anti-Patterns 섹션 작성.
+5. 완료 후: bash scripts/init-ref-docs.sh --register --stack ${stack} --role ${role} --sources "<url1>,<url2>,<url3>" ${PROJECT_ROOT}
+${legacy_hint}
+───────────────────────────────────────────────
+PROMPT
+}
+
+# ───── register: 메타 기록 ─────
+register_meta() {
+  local role="$1" stack="$2" sources_csv="$3"
+  local ts key sources_json
+  ts=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+  key="${role}-${stack}"
+  sources_json=$(echo "$sources_csv" | awk -F',' 'BEGIN{printf "["} {for(i=1;i<=NF;i++){printf (i>1?",":"") "\"" $i "\""}} END{printf "]"}')
+  [ -z "$sources_csv" ] && sources_json="[]"
+  jq --arg k "$key" --arg ts "$ts" --argjson s "$sources_json" '.[$k] = {"generated_at": $ts, "sources": $s, "status": "filled"}' "$META" > "${META}.tmp" && mv "${META}.tmp" "$META"
+  echo "registered: $key (sources=$(echo "$sources_json" | jq 'length'))"
+}
+
+# ───── 한 스택 처리 ─────
+process_one() {
+  local role="$1" stack="$2"
+  local path="${REF_DIR}/${role}-${stack}.md"
+
+  if [ -f "$path" ] && ! $REFRESH; then
+    echo "skip: $path 이미 존재 (--refresh 로 강제 재생성)"
+    return 0
+  fi
+  if [ -f "$path" ] && $REFRESH; then
+    local backup="${ARCHIVE_DIR}/ref-${role}-${stack}-$(date +%Y%m%d%H%M%S).md"
+    cp "$path" "$backup"
+    echo "archived: $backup"
+  fi
+
+  local answer="y"
+  if ! $YES; then
+    printf "Generate ref-docs for %s-%s? [y/N] " "$role" "$stack"
+    read -r answer </dev/tty || answer="n"
+  fi
+  case "$answer" in
+    y|Y|yes|YES) ;;
+    *) echo "skipped: $role-$stack"; return 3 ;;
+  esac
+
+  case "$MODE" in
+    placeholder)
+      write_placeholder "$role" "$stack" "$path"
+      local ts; ts=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+      jq --arg k "${role}-${stack}" --arg ts "$ts" '.[$k] = {"generated_at": $ts, "sources": [], "status": "placeholder"}' "$META" > "${META}.tmp" && mv "${META}.tmp" "$META"
+      echo "wrote: $path (placeholder)"
+      ;;
+    claude-prompt)
+      emit_claude_prompt "$role" "$stack" "$path"
+      ;;
+    *)
+      echo "ERROR: interactive 모드는 --placeholder 또는 --claude-prompt 중 하나를 지정하세요." >&2
+      return 1
+      ;;
+  esac
+}
+
+# ───── main ─────
+case "$MODE" in
+  dry-run)
+    echo "detected stacks:"
+    detect_stacks | sed 's/^/  - /'
+    echo ""
+    echo "ref files 예상 경로 (미존재 시 생성 대상):"
+    while IFS=':' read -r role stack; do
+      path="${REF_DIR}/${role}-${stack}.md"
+      if [ -f "$path" ]; then
+        echo "  [exists] $path"
+      else
+        echo "  [create] $path"
+      fi
+    done < <(detect_stacks)
+    ;;
+  register)
+    [ -z "$STACK" ] || [ -z "$ROLE" ] && { echo "ERROR: --register 는 --stack --role --sources 필요" >&2; exit 1; }
+    register_meta "$ROLE" "$STACK" "$SOURCES"
+    ;;
+  placeholder|claude-prompt)
+    if [ -n "$STACK" ] && [ -n "$ROLE" ]; then
+      process_one "$ROLE" "$STACK"
+    else
+      # 감지된 전체 스택을 순회
+      while IFS=':' read -r role stack; do
+        process_one "$role" "$stack"
+      done < <(detect_stacks)
+    fi
+    ;;
+  interactive)
+    echo "ERROR: 모드 지정 필요 — --dry-run | --placeholder | --claude-prompt | --register" >&2
+    echo "자세한 사용법: bash $0 --help" >&2
+    exit 1
+    ;;
+esac