moai-adk 0.3.2__py3-none-any.whl → 0.3.6__py3-none-any.whl

moai_adk/templates/.moai/memory/development-guide.md

@@ -69,48 +69,23 @@ MoAI-ADK는 Anthropic의 "Effective Context Engineering for AI Agents" 원칙을
 |--------|----------|------------|------------|
 | `/alfred:1-spec` | product.md | structure.md, tech.md | SPEC 후보 발굴 시 |
 | `/alfred:2-build` | SPEC-XXX/spec.md | development-guide.md | TDD 구현 시작 시 |
-| `/alfred:3-sync` | sync-report.md | TAG 인덱스 | 문서 동기화 시 |
+| `/alfred:3-sync` | sync-report.md | TAG 체인 검증 (`rg` 스캔) | 문서 동기화 시 |
 
 **구현 방법**:
 - Alfred는 커맨드 실행 시점에 필요한 문서만 `Read` 도구로 로드
 - 에이전트는 자신의 작업에 필요한 문서만 요청
 - CLAUDE.md의 "메모리 전략" 섹션에 명시된 5개 문서는 항상 로드
 
-### 2. Compaction (압축)
-
-**원칙**: 긴 세션(>70% 토큰 사용)은 요약 후 새 세션으로 재시작
-
-**Compaction 트리거**:
-- 토큰 사용량 > 140,000 (총 200,000의 70%)
-- 대화 턴 수 > 50회
-- 사용자가 명시적으로 `/clear` 또는 `/new` 실행
-
-**Compaction 절차**:
-1. **요약 생성**: 현재 세션의 핵심 결정사항, 완료된 작업, 다음 단계를 요약
-2. **새 세션 시작**: 요약 내용을 새 세션의 첫 메시지로 전달
-3. **권장 사항 안내**: 사용자에게 `/clear` 또는 `/new` 명령 사용 권장
-
-**예시**:
-```markdown
-**권장사항**: 다음 단계 진행 전 `/clear` 또는 `/new` 명령으로 새로운 대화 세션을 시작하면 더 나은 성능과 컨텍스트 관리를 경험할 수 있습니다.
-```
-
 ### Context Engineering 체크리스트
 
 **커맨드 설계 시**:
 - [ ] JIT: 필요한 문서만 로드하는가?
 - [ ] 선택적 로드: 조건부로 문서를 로드하는가?
-- [ ] Compaction: 긴 작업 시 중간 요약을 제공하는가?
 
 **에이전트 설계 시**:
 - [ ] 최소 도구: 필요한 도구만 YAML frontmatter에 선언했는가?
 - [ ] 명확한 역할: 단일 책임 원칙을 준수하는가?
 
-**장기 세션 관리**:
-- [ ] 토큰 사용량 모니터링
-- [ ] 70% 초과 시 Compaction 권장
-- [ ] `/clear` 또는 `/new` 안내 문구 포함
-
 ---
 
 ## TRUST 5원칙

moai_adk/templates/.moai/memory/gitflow-protection-policy.md

@@ -0,0 +1,220 @@
+# GitFlow 권장 정책 (Advisory Policy)
+
+**문서 ID**: @DOC:GITFLOW-POLICY-001
+**작성일**: 2025-10-17
+**상태**: Advisory (권장 사항, 강제 아님)
+**적용 범위**: Personal/Team 모드 모두
+
+---
+
+## 개요
+
+MoAI-ADK는 GitFlow 전략을 **권장**합니다. 이 정책은 best practice를 제시하지만, 사용자의 판단에 따라 유연하게 적용할 수 있습니다.
+
+## 핵심 권장사항
+
+### 1. Main 브랜치 접근 제어 (권장)
+
+| 권장사항 | 설명 | 적용 방식 |
+|---------|------|----------|
+| **Develop 기반 Merge** | develop 브랜치에서 main으로 머지 권장 | Advisory ⚠️ |
+| **Feature는 Develop** | Feature 브랜치는 develop에서 분기하고 develop으로 PR 생성 | Advisory ⚠️ |
+| **Release 프로세스** | Release: develop -> main (Release Engineer 권장) | Advisory ⚠️ |
+| **강제 Push** | Force-push 시 경고, 하지만 허용 | Warning ⚠️ |
+| **직접 Push** | main 직접 push 시 경고, 하지만 허용 | Warning ⚠️ |
+
+### 2. Git Workflow (권장)
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                RECOMMENDED GITFLOW                      │
+└─────────────────────────────────────────────────────────┘
+
+        develop (권장 기본 브랜치)
+          ↑     ↓
+    ┌─────────────────┐
+    │                 │
+    │ (개발자가 작업)  │
+    │                 │
+    ↓                 ↑
+feature/SPEC-{ID}   [PR: feature -> develop]
+                     [코드 리뷰 + 승인]
+                     [Merge to develop]
+
+    develop (안정적)
+         ↓
+         │ (Release Manager가 준비)
+         ↓
+    [PR: develop -> main]
+    [CI/CD 검증]
+    [태그 생성]
+         ↓
+       main (릴리스)
+```
+
+**유연성**: 프로젝트 상황에 따라 직접 main 푸시도 가능하지만, 위 워크플로우를 권장합니다.
+
+## 기술 구현
+
+### Pre-push Hook (Advisory Mode)
+
+**위치**: `.git/hooks/pre-push`
+**기능**: Main 브랜치 작업 시 경고 표시 (차단 안 함)
+
+```bash
+# main으로 push 시도 시:
+⚠️  ADVISORY: Non-standard GitFlow detected
+
+Current branch: feature/SPEC-123
+Target branch: main
+
+Recommended GitFlow workflow:
+  1. Work on feature/SPEC-{ID} branch (created from develop)
+  2. Push to feature/SPEC-{ID} and create PR to develop
+  3. Merge into develop after code review
+  4. When develop is stable, create PR from develop to main
+  5. Release manager merges develop -> main with tag
+
+✓ Push will proceed (flexibility mode enabled)
+```
+
+### 강제 Push Advisory
+
+```bash
+⚠️  ADVISORY: Force-push to main branch detected
+
+Recommended approach:
+  - Use GitHub PR with proper code review
+  - Ensure changes are merged via fast-forward
+
+✓ Push will proceed (flexibility mode enabled)
+```
+
+---
+
+## 사용 사례별 워크플로우
+
+### 사례 1: 표준 Feature 개발 (권장)
+
+```bash
+# 1. develop에서 최신 코드 받기
+git checkout develop
+git pull origin develop
+
+# 2. feature 브랜치 생성 (develop에서)
+git checkout -b feature/SPEC-001-new-feature
+
+# 3. 작업 진행
+# ... 코드 작성 및 테스트 ...
+
+# 4. 커밋
+git add .
+git commit -m "..."
+
+# 5. Push
+git push origin feature/SPEC-001-new-feature
+
+# 6. GitHub에서 PR 생성: feature/SPEC-001-new-feature -> develop
+
+# 7. 코드 리뷰 및 승인 후 머지 (develop으로)
+```
+
+### 사례 2: 빠른 Hotfix (유연한 방식)
+
+```bash
+# 긴급 수정이 필요한 경우:
+
+# 옵션 1: 권장 방식 (develop 기반)
+git checkout develop
+git checkout -b hotfix/critical-bug
+# ... 수정 ...
+git push origin hotfix/critical-bug
+# PR 생성: hotfix -> develop -> main
+
+# 옵션 2: 직접 main 수정 (허용되지만 권장하지 않음)
+git checkout main
+# ... 수정 ...
+git commit -m "Fix critical bug"
+git push origin main  # ⚠️ Advisory 경고 표시되지만 진행됨
+```
+
+### 사례 3: Release (표준 또는 유연)
+
+```bash
+# 표준 방식 (권장):
+git checkout develop
+gh pr create --base main --head develop --title "Release v1.0.0"
+
+# 직접 push 방식 (허용):
+git checkout develop
+git push origin main  # ⚠️ Advisory 경고 표시되지만 진행됨
+git tag -a v1.0.0 -m "Release v1.0.0"
+git push origin v1.0.0
+```
+
+---
+
+## 정책 모드 비교
+
+### Strict Mode (이전 방식, 현재 비활성)
+
+- ❌ main 직접 push 차단
+- ❌ force-push 차단
+- ❌ develop 외 브랜치에서 main 머지 차단
+
+### Advisory Mode (현재 활성, v0.3.5+)
+
+- ⚠️ main 직접 push 시 경고 + 허용
+- ⚠️ force-push 시 경고 + 허용
+- ⚠️ best practice 권장 + 유연성 제공
+- ✅ 사용자 판단 존중
+
+---
+
+## 권장 체크리스트
+
+프로젝트에 참여하는 모든 팀원은 다음을 권장합니다:
+
+- [ ] `.git/hooks/pre-push` 파일 존재 및 실행 가능 (755 권한)
+- [ ] develop 브랜치에서 feature 분기 (권장)
+- [ ] PR 생성 시 대상이 develop (권장)
+- [ ] Release는 develop -> main (권장)
+
+**검증 명령**:
+```bash
+ls -la .git/hooks/pre-push
+git branch -vv
+```
+
+---
+
+## FAQ
+
+**Q: develop -> main이 아닌 다른 경로로 머지할 수 있나요?**
+A: 가능합니다. Advisory 경고가 표시되지만 진행됩니다. 단, develop -> main을 권장합니다.
+
+**Q: Force-push를 할 수 있나요?**
+A: 가능합니다. 경고가 표시되지만 허용됩니다. 단, 신중하게 사용하세요.
+
+**Q: Main으로 직접 commit/push할 수 있나요?**
+A: 가능합니다. Advisory 경고가 표시되지만 진행됩니다.
+
+**Q: Hook을 완전히 비활성화할 수 있나요?**
+A: 가능합니다. `.git/hooks/pre-push` 파일을 삭제하거나 실행 권한을 제거하세요.
+
+**Q: 왜 Advisory Mode로 변경했나요?**
+A: 사용자의 유연성과 판단을 존중하면서도 best practice를 권장하기 위해서입니다.
+
+---
+
+## 정책 업데이트 이력
+
+| 날짜 | 내용 | 담당자 |
+|------|------|--------|
+| 2025-10-17 | 초기 정책 수립 (Strict Mode) | git-manager |
+| 2025-10-17 | Advisory Mode로 전환 (경고만, 차단 안 함) | git-manager |
+
+---
+
+**이 정책은 권장사항이며, 사용자의 판단에 따라 유연하게 적용할 수 있습니다.**
+**질문이나 제안사항은 팀 리드 또는 Release Engineer와 협의하세요.**