modu-ai
diff --git a/‎.claude/commands/99-release.md‎
Lines changed: 69 additions & 26 deletions b/‎.claude/commands/99-release.md‎
Lines changed: 69 additions & 26 deletions
diff --git a/‎.github/ISSUE_TEMPLATE/release.md‎
Lines changed: 92 additions & 0 deletions b/‎.github/ISSUE_TEMPLATE/release.md‎
Lines changed: 92 additions & 0 deletions
diff --git a/‎.github/PULL_REQUEST_TEMPLATE.md‎
Lines changed: 50 additions & 20 deletions b/‎.github/PULL_REQUEST_TEMPLATE.md‎
Lines changed: 50 additions & 20 deletions
@@ -1,29 +1,44 @@
 ---
-description: "MoAI-ADK v2.x production release via GitHub Flow. Creates release/vX.Y.Z branch, version bump, CHANGELOG, PR to main, squash merge, then tag push. Tag vX.Y.Z triggers GoReleaser. All git operations delegated to manager-git. Quality failures escalate to expert-debug."
-argument-hint: "[VERSION] - optional target version (e.g., 2.1.0). If omitted, prompts for patch/minor/major selection."
+description: "MoAI-ADK production release via Enhanced GitHub Flow (CLAUDE.local.md §18). Creates release/vX.Y.Z branch, version bump, CHANGELOG (bilingual), PR to main, merge commit (NOT squash), then scripts/release.sh for tag + GoReleaser. Hotfix support via --hotfix flag. All git operations delegated to manager-git. Quality failures escalate to expert-debug."
+argument-hint: "[VERSION] [--hotfix] - optional target version (e.g., 2.1.0). If omitted, prompts for patch/minor/major selection."
 type: local
 allowed-tools: Read, Write, Edit, Grep, Glob, Bash, AskUserQuestion, Agent, TaskCreate, TaskUpdate, TaskList, TaskGet
 disable-model-invocation: true
-version: 4.0.0
+version: 5.0.0
 metadata:
   release_target: "production"
   branch: "main"
   tag_format: "vX.Y.Z"
-  changelog_format: "korean_first"
+  changelog_format: "english_first_bilingual"
   release_notes_format: "bilingual"
   git_delegation: "required"
   quality_escalation: "expert-debug"
+  workflow_model: "enhanced-github-flow"
+  merge_strategy: "merge-commit"
+  reference_policy: "CLAUDE.local.md §18"
 ---
 
-## Release Configuration
+## Release Configuration (Enhanced GitHub Flow)
 
-- **Git workflow**: GitHub Flow with enforce_admins (direct main push blocked)
-- **Release branch**: `release/vX.Y.Z` (created from main, merged via PR)
-- **Target branch**: `main` (all releases merge to main)
-- **Tag format**: `vX.Y.Z` (standard semver, triggers GoReleaser via `.github/workflows/release.yml`)
-- **Merge strategy**: Squash merge with branch auto-delete
+- **Git workflow**: Enhanced GitHub Flow (CLAUDE.local.md §18, Gitflow 비채택)
+- **Release branch**: `release/vX.Y.Z` (main에서 분기, PR 경유 머지)
+- **Hotfix branch**: `hotfix/vX.Y.Z-*` (최신 tag에서 분기, main으로 머지)
+- **Target branch**: `main` (production releases only)
+- **Tag format**: `vX.Y.Z` (SemVer, GoReleaser trigger via `.github/workflows/release.yml`)
+- **[HARD] Merge strategy**: **Merge commit** (`gh pr merge --merge --delete-branch`) — release PR에 반드시 적용. Squash 금지 (개별 SPEC commit 보존 필수, §18.3)
+- **Tag push tool**: `./scripts/release.sh vX.Y.Z` 또는 `make release V=vX.Y.Z` (§18.8) — 수동 `git tag + push` 금지 (CHANGELOG 검증 + CI 확인 + GoReleaser watch 포함)
+- **Label 3축**: PR에 `type:*` + `priority:*` + `area:*` 필수 (§18.6)
 - **Release URL**: https://github.com/modu-ai/moai-adk/releases/tag/vX.Y.Z
-- **Binaries**: darwin-arm64, darwin-amd64, linux-arm64, linux-amd64, windows-amd64
+- **Binaries**: darwin-arm64/amd64, linux-arm64/amd64, windows-arm64/amd64 (6 assets + checksums.txt)
+
+### Tool Selection Guide (§18.8 이중 경로)
+
+| 시나리오 | 도구 | 이유 |
+|---------|------|------|
+| Patch/Minor 자동 릴리스 (CHANGELOG 이미 작성됨) | `./scripts/release.sh vX.Y.Z` | 최소 interaction, CI 확인 포함 |
+| Major release / breaking changes | `/99-release` (이 커맨드) | 완전한 리뷰 + 단계별 확인 흐름 |
+| Hotfix 긴급 대응 | `./scripts/release.sh vX.Y.Z --hotfix` | main 외 브랜치 허용, 빠른 경로 |
+| CHANGELOG 작성 + release 통합 | `/99-release` (이 커맨드) | Phase 4에서 bilingual CHANGELOG 생성 |
 
 ---
 
@@ -349,26 +364,49 @@ Agent(
 3. Wait for CI checks to pass:
    `gh pr checks --watch`
 
-4. Merge PR with squash:
-   `gh pr merge --squash --delete-branch`
+4. **[HARD] Merge PR with merge commit (NOT squash)** — Enhanced GitHub Flow §18.3 준수:
+   `gh pr merge --merge --delete-branch`
+
+   이유: release/vX.Y.Z 브랜치의 개별 commit (version bump + CHANGELOG + 필요 시 추가 fix)을 main history에 보존하여 릴리스 시점 추적 가능. Squash 시 개별 SPEC 구현 commit이 소실됨 (v2.14.0 Case Study §18.11 참조).
 
 5. Sync local main with merged result:
    ```bash
    git checkout main
    git pull origin main
    ```
 
-6. Check remote status: Verify if tag vX.Y.Z exists on remote (origin)
-7. Handle tag conflicts:
-   - If remote does NOT have vX.Y.Z: Create tag on current main HEAD and push
-   - If remote already has vX.Y.Z: Report situation with options
-8. Create and push tag (only if tag does NOT exist on remote):
+6. **[HARD] Tag creation via scripts/release.sh** (§18.8) — 수동 `git tag + push` 금지:
+   ```bash
+   ./scripts/release.sh vX.Y.Z
+   # OR (Makefile)
+   make release V=vX.Y.Z
+   ```
+
+   스크립트가 자동으로:
+   - CHANGELOG.md 해당 버전 섹션 존재 확인
+   - CI 상태 조회 (`gh api /commits/{sha}/status`)
+   - main 브랜치 + origin 동기화 확인
+   - 기존 tag 충돌 검사 (local + remote)
+   - CHANGELOG 섹션 → annotated tag annotation 자동 추출
+   - 사용자 confirmation prompt
+   - Tag 생성 + push → GoReleaser workflow 자동 trigger
+   - GoReleaser workflow watch + GitHub Release 검증
+
+   Hotfix 경우:
    ```bash
-   # Only execute this block if vX.Y.Z tag does NOT exist on origin
-   git tag vX.Y.Z
+   ./scripts/release.sh vX.Y.Z --hotfix  # main 외 브랜치 허용
+   ```
+
+   **Fallback** (스크립트 실패 시): manager-git이 수동 tag 생성 — 단, 반드시 CHANGELOG 검증 수행 후
+   ```bash
+   # CHANGELOG.md 에 ## [X.Y.Z] 섹션 존재 확인
+   grep "^## \[X.Y.Z\]" CHANGELOG.md
+   # Tag 생성 + push
+   git tag -a vX.Y.Z -m "vX.Y.Z — [요약]"
    git push origin vX.Y.Z
    ```
-9. Verify GoReleaser workflow triggered (tags bypass branch protection)
+
+7. Verify GoReleaser workflow triggered (tags bypass branch protection)
 
 ### Expected Output
 
@@ -670,19 +708,24 @@ Updating version files...
 
 ---
 
-## Key Rules
+## Key Rules (Enhanced GitHub Flow §18)
 
 - **Target branch**: `main` (production releases)
-- **Git workflow**: GitHub Flow with enforce_admins (direct main push blocked)
-- **Release flow**: release/vX.Y.Z branch → PR → squash merge → tag → push tag
-- **Tag format**: `vX.Y.Z` (triggers GoReleaser via release.yml)
+- **Git workflow**: Enhanced GitHub Flow (CLAUDE.local.md §18, Gitflow 비채택)
+- **[HARD] Release flow**: release/vX.Y.Z branch → PR → **merge commit** (NOT squash) → `./scripts/release.sh` → GoReleaser auto-release
+- **[HARD] Hotfix flow**: hotfix/vX.Y.Z-* branch → PR → **merge commit** → `./scripts/release.sh --hotfix` (§18.5)
+- **Tag format**: `vX.Y.Z` (SemVer, triggers GoReleaser via release.yml)
 - Tags bypass branch protection (only branch pushes are blocked)
 - Tests MUST pass to continue (85%+ coverage per package)
-- All 3 version files must be consistent
+- All 3 version files must be consistent (pkg/version, .moai/config, internal/template/templates/.moai/config)
 - **[HARD] CHANGELOG and GitHub Release: English FIRST, Korean SECOND**
+- **[HARD] Release PR: `--merge` (NOT `--squash`)** — 개별 SPEC commit 보존 (§18.3, v2.14.0 Case Study)
+- **[HARD] Tag push via `scripts/release.sh` only** — 수동 `git tag + push` 금지 (§18.8, CHANGELOG 검증 누락 방지)
 - **[HARD] ALL git operations MUST be delegated to manager-git agent**
 - **[HARD] Quality gate failures MUST be delegated to expert-debug agent**
 - **[HARD] Never `git push origin main` — always use PR merge flow**
+- **[HARD] Label 3축** (type/priority/area) PR 부착 필수 (§18.6) — Release Drafter 자동 분류용
+- **[HARD] Release Drafter draft 참조** (§18.9) — PR merge 시 자동 업데이트되는 draft를 CHANGELOG.md 작성에 활용
 
 ---
 
 
@@ -0,0 +1,92 @@
+---
+name: Release
+about: Release tracking issue (Minor/Major/Hotfix)
+title: "release: vX.Y.Z — <release theme>"
+labels: ["type:chore", "priority:P1", "area:ci"]
+assignees: []
+---
+
+## Release Plan
+
+**Version**: `vX.Y.Z`
+**Type**: [ Minor | Major | Patch | Hotfix ]
+**Target date**: <YYYY-MM-DD>
+**Release branch**: `release/vX.Y.Z` (Minor/Major only) or `hotfix/vX.Y.Z-*` (Hotfix)
+
+## Scope
+
+<!-- SPEC-IDs included in this release -->
+
+- [ ] SPEC-XXX-001: ...
+- [ ] SPEC-XXX-002: ...
+
+## Pre-Release Checklist (CLAUDE.local.md §18.8)
+
+### Code Quality
+- [ ] 모든 SPEC 구현 완료 (`status: implemented` 로 전환)
+- [ ] 51/51 (또는 전체) ACs PASS
+- [ ] `go test -race ./...` PASS (ubuntu/macos/windows CI)
+- [ ] `golangci-lint run ./...` 0 issues
+- [ ] `manager-quality` review 통과 (TRUST 5 ≥ 4/5)
+
+### Documentation
+- [ ] `CHANGELOG.md` 에 `## [X.Y.Z] - YYYY-MM-DD` 섹션 추가 (영문 + 한국어)
+- [ ] Non-breaking 선언 또는 Breaking Changes 섹션 명시
+- [ ] Detection Improvements 섹션 (UX 영향 있는 감지 변경 시)
+- [ ] Deferred items 섹션 (next minor/major 예약 항목)
+- [ ] README.md version line 업데이트 (필요 시)
+
+### Git State
+- [ ] `release/vX.Y.Z` 브랜치 또는 main 최신
+- [ ] 모든 PR merge 완료
+- [ ] 작업 트리 clean (`git status --short` empty)
+- [ ] origin/main과 동기화 (local/remote SHA 일치)
+
+### Branch Protection (admin)
+- [ ] `main` branch protection 활성화 (CI required, 1 review)
+- [ ] Force push 차단 확인
+
+## Release Execution
+
+Minor/Major Release:
+```bash
+# 1. release 브랜치에서 main으로 PR 생성 + merge commit
+gh pr merge <release-PR> --merge --delete-branch
+
+# 2. main pull + 릴리스 스크립트
+git checkout main && git pull origin main
+./scripts/release.sh vX.Y.Z
+# OR: make release V=vX.Y.Z
+```
+
+Hotfix Release:
+```bash
+# 1. main의 latest tag에서 분기
+git checkout -b hotfix/vX.Y.Z-<topic> <latest-tag>
+
+# 2. 수정 + PR + merge commit
+gh pr merge <hotfix-PR> --merge --delete-branch
+
+# 3. Release 스크립트 실행
+git checkout main && git pull origin main
+./scripts/release.sh vX.Y.Z --hotfix
+# OR: make release-hotfix V=vX.Y.Z
+```
+
+## Post-Release Checklist
+
+- [ ] GitHub Release 생성 확인 (GoReleaser 자동)
+- [ ] Release assets 5 플랫폼 업로드 확인 (darwin amd64/arm64, linux amd64/arm64, windows amd64)
+- [ ] `latest` release marker 확인
+- [ ] docs-site 4개국어 reference 페이지 업데이트 (별도 PR, `docs/vX.Y.Z-reference-sync`)
+- [ ] v2.X+1 backlog SPEC 분석 및 초안 작성 (next cycle kickoff)
+- [ ] Release announcement (선택: Discord, Twitter, blog)
+- [ ] 이 Issue close
+
+## Release Notes
+
+<!-- Post-release: 간단한 release 요약 붙여넣기 -->
+
+---
+
+**Reference**: CLAUDE.local.md §18 Enhanced GitHub Flow
@@ -10,36 +10,66 @@
 
 ## Type of Change
 
-- [ ] Bug fix (non-breaking change that fixes an issue)
-- [ ] New feature (non-breaking change that adds functionality)
-- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
-- [ ] Documentation update
-- [ ] Refactoring (no functional changes)
-- [ ] CI/CD changes
-- [ ] Dependencies update
+<!-- Select ONE primary type — see CLAUDE.local.md §18.6 for label 3축 체계 -->
+
+- [ ] `type:feature` — New capability (non-breaking)
+- [ ] `type:fix` — Bug fix (non-breaking)
+- [ ] `type:docs` — Documentation only
+- [ ] `type:chore` — Maintenance (dependencies, cleanup)
+- [ ] `type:ci` — CI/CD / GitHub Actions
+- [ ] `type:refactor` — Code restructuring (no behavior change)
+- [ ] `type:security` — Security fix or hardening
+- [ ] `type:test` — Test additions or improvements
+- [ ] **Breaking change** — Public API change (requires major version bump)
+
+## Merge Strategy (CLAUDE.local.md §18.3)
+
+<!-- Reviewer: use the correct `gh pr merge` flag -->
+
+- [ ] **`--squash`** (default for `feat/`, `fix/`, `chore/`, `docs/`, `plan/` branches) — WIP commit 정리
+- [ ] **`--merge`** (`release/` or `hotfix/` branches) — 릴리스 마일스톤 + 개별 SPEC commit 보존
+- [ ] **Dependabot auto-merge** (dependabot/* branches) — 자동 squash
+
+> ⚠️ Release PR (`release/vX.Y.Z → main`)은 반드시 `--merge` 사용. Squash 시 개별 feature history 손실.
 
 ## Testing
 
-- [ ] Tests pass locally (`go test ./...`)
-- [ ] Race detection passes (`go test -race ./...`)
-- [ ] Linting passes (`golangci-lint run`)
-- [ ] New tests added for new functionality
-- [ ] Coverage maintained at 85%+
+- [ ] `go test ./...` 통과
+- [ ] `go test -race ./...` (race detection) 통과
+- [ ] `golangci-lint run` 통과
+- [ ] 새 기능에 대한 테스트 추가됨
+- [ ] 커버리지 85%+ 유지
+
+## Quality Gates
+
+- [ ] CI all checks green (Lint, Test ubuntu/macos/windows, Build 5 platforms, CodeQL)
+- [ ] `@MX` tag 규율 준수 (fan_in ≥ 3 → ANCHOR, goroutine/complexity ≥ 15 → WARN, 필수 `@MX:REASON`)
+- [ ] SPEC 변경 시 frontmatter `status` 필드 적절히 업데이트 (draft → implemented)
+- [ ] SARIF / wire format 등 public contract 불변 (non-breaking 보장)
 
 ## AI Collaboration
 
-- [ ] This PR was created with AI assistance (Claude Code, Codex, or other)
-- [ ] AI-generated code has been reviewed by a human
-- [ ] AI agent name/tool noted in commit messages (Co-Authored-By)
+- [ ] AI 도구 (Claude Code, Codex 등) 협업으로 생성됨
+- [ ] AI 생성 코드가 사람에 의해 리뷰됨
+- [ ] AI agent 이름이 commit 메시지에 명시됨 (Co-Authored-By 또는 footer)
 
 ## Checklist
 
-- [ ] Code follows the project's coding standards (English comments, Go conventions)
-- [ ] Self-reviewed my own code
-- [ ] Commented hard-to-understand areas
-- [ ] Updated documentation if needed
-- [ ] No secrets or credentials in the changes
+- [ ] 프로젝트 코딩 표준 준수 (Go convention, 주석 한국어, 식별자 영어)
+- [ ] Self-review 완료
+- [ ] 이해하기 어려운 부분에 주석 추가
+- [ ] 필요 시 문서 업데이트 (README, CHANGELOG, docs-site)
+- [ ] Secrets/credentials 포함 없음
+- [ ] Branch 명명 규칙 준수 (§18.2)
 
 ## Related Issues
 
 <!-- Link related issues: Fixes #123, Refs #456 -->
+
+## Post-Merge Actions (release PR 전용)
+
+<!-- Release PR 머지 후 실행 -->
+
+- [ ] `./scripts/release.sh vX.Y.Z` 로 tag + GoReleaser 자동 실행
+- [ ] GitHub Release 생성 확인 (GoReleaser 자동)
+- [ ] docs-site 4개국어 reference 페이지 업데이트 (별도 PR)