aiwf 0.3.8 → 0.3.12

package/.aiwf/01_PROJECT_DOCS/FEATURE_LEDGER_FAQ.md

@@ -1,365 +0,0 @@
-# Feature Ledger FAQ & Troubleshooting Guide
-
-## 자주 묻는 질문 (FAQ)
-
-### 일반 질문
-
-#### Q: Feature Ledger와 일반 Task의 차이점은 무엇인가요?
-
-**A:** Feature Ledger는 더 큰 범위의 기능 개발을 추적합니다:
-
-| 항목 | Feature Ledger | Task |
-|------|----------------|------|
-| 범위 | 전체 기능 (1-2주) | 단일 작업 (1-2일) |
-| 추적 | Git, PR, 진행률 | 완료 여부 |
-| 팀 | 여러 명 가능 | 보통 1명 |
-| 출력물 | 배포 가능한 기능 | 코드 변경 |
-
-#### Q: Feature ID는 어떻게 생성되나요?
-
-**A:** Feature ID는 자동으로 순차 생성됩니다:
-- 형식: `FL###` (FL001, FL002, ...)
-- 재사용 불가
-- 삭제된 ID도 재사용하지 않음
-- 수동 지정 불가
-
-#### Q: 완료된 Feature를 다시 활성화할 수 있나요?
-
-**A:** 아니요, 완료된 Feature는 다시 활성화할 수 없습니다. 추가 작업이 필요한 경우:
-1. 새로운 Feature를 생성하여 개선 사항 추적
-2. 원본 Feature를 참조 (`depends_on: [FL001]`)
-3. 명확한 범위로 새 작업 정의
-
-#### Q: Feature와 GitHub Issue를 어떻게 연결하나요?
-
-**A:** 여러 방법이 있습니다:
-
-1. **자동 연결**: PR 제목에 Feature ID 포함
-   ```
-   feat(FL001): Implement user authentication
-   ```
-
-2. **수동 연결**: 명령어 사용
-   ```bash
-   /project:aiwf:link_feature_issue FL001 #42
-   ```
-
-3. **Issue 본문에 참조**:
-   ```markdown
-   Related Feature: FL001
-   ```
-
-### 사용법 질문
-
-#### Q: 여러 스프린트에 걸친 Feature는 어떻게 관리하나요?
-
-**A:** `sprint_ids` 배열을 사용합니다:
-
-```yaml
-sprint_ids: [S01_M02, S02_M02, S03_M02]
-```
-
-각 스프린트에서:
-1. 해당 스프린트의 작업만 Task로 생성
-2. Feature 진행률은 전체 기준으로 업데이트
-3. 스프린트별 진행 상황을 Progress Log에 기록
-
-#### Q: Feature 진행률은 어떻게 계산하나요?
-
-**A:** 세 가지 방법이 있습니다:
-
-1. **수동 업데이트**:
-   ```bash
-   /project:aiwf:update_feature_progress FL001 75
-   ```
-
-2. **체크리스트 기반**:
-   ```
-   완료 항목 / 전체 항목 × 100
-   ```
-
-3. **연결된 Task 기반**:
-   ```
-   완료 Task / 전체 Task × 100
-   ```
-
-#### Q: Feature 템플릿을 커스터마이징할 수 있나요?
-
-**A:** 네, 가능합니다:
-
-1. 기본 템플릿 복사:
-   ```bash
-   cp .aiwf/99_TEMPLATES/feature_template.md .aiwf/99_TEMPLATES/my_feature_template.md
-   ```
-
-2. 템플릿 수정
-
-3. 사용:
-   ```bash
-   /project:aiwf:create_feature_ledger new_feature --template my_feature_template
-   ```
-
-### 통합 질문
-
-#### Q: CI/CD 파이프라인과 어떻게 통합하나요?
-
-**A:** GitHub Actions 예제:
-
-```yaml
-- name: Update Feature on Deploy
-  if: success()
-  run: |
-    FEATURE_ID=$(git log -1 --pretty=%B | grep -oP 'FL\d{3}')
-    if [ ! -z "$FEATURE_ID" ]; then
-      npx aiwf update_feature_progress $FEATURE_ID 90 --comment "Deployed to staging"
-    fi
-```
-
-#### Q: 여러 저장소에서 하나의 Feature를 작업할 때는?
-
-**A:** Cross-repo Feature 추적:
-
-1. 메인 저장소에 Feature Ledger 생성
-2. 다른 저장소에서 커밋 시 Feature ID 참조
-3. 정기적으로 동기화:
-   ```bash
-   /project:aiwf:feature_sync --cross-repo
-   ```
-
-## 문제 해결 가이드
-
-### 일반적인 오류
-
-#### Error E001: Feature ID not found
-
-**증상**:
-```
-Error E001: Feature ID 'FL099' not found
-```
-
-**원인**:
-- 잘못된 Feature ID
-- Feature가 다른 디렉토리에 있음
-
-**해결**:
-```bash
-# 올바른 ID 확인
-cat .aiwf/06_FEATURE_LEDGERS/FEATURE_LEDGER_INDEX.md
-
-# 모든 Feature 검색
-find .aiwf/06_FEATURE_LEDGERS -name "*.md" | grep -v INDEX
-```
-
-#### Error E002: Invalid status transition
-
-**증상**:
-```
-Error E002: Cannot transition from 'completed' to 'active'
-```
-
-**원인**:
-- 허용되지 않는 상태 전환
-- Feature가 이미 archived 상태
-
-**해결**:
-1. 현재 상태 확인
-2. [상태 전이 다이어그램](./FEATURE_LEDGER_SYSTEM_OVERVIEW.md#상태-전이-다이어그램) 참조
-3. 필요시 새 Feature 생성
-
-#### Error E003: Duplicate feature ID
-
-**증상**:
-```
-Error E003: Feature ID 'FL001' already exists
-```
-
-**원인**:
-- ID 생성 시퀀스 오류
-- 수동으로 파일 생성
-
-**해결**:
-```bash
-# 인덱스 재구성
-/project:aiwf:feature_index --rebuild
-
-# 다음 가용 ID 확인
-/project:aiwf:feature_next_id
-```
-
-### Git 통합 문제
-
-#### 브랜치 생성 실패
-
-**증상**:
-```
-Failed to create branch: feature/FL001-user-auth
-```
-
-**원인**:
-- 브랜치가 이미 존재
-- Git 저장소가 아님
-- 권한 부족
-
-**해결**:
-```bash
-# 기존 브랜치 확인
-git branch -a | grep FL001
-
-# 강제 생성
-/project:aiwf:feature_branch FL001 create --force
-
-# 수동 생성
-git checkout -b feature/FL001-user-auth
-```
-
-#### 커밋 연결 안 됨
-
-**증상**: 커밋했는데 Feature에 반영되지 않음
-
-**원인**:
-- 커밋 메시지에 Feature ID 없음
-- 자동 동기화 비활성화
-
-**해결**:
-```bash
-# 수동 연결
-/project:aiwf:link_feature_commit FL001 --commit HEAD
-
-# 자동 동기화 활성화
-export AIWF_AUTO_SYNC=true
-```
-
-### 성능 문제
-
-#### 대시보드 생성이 느림
-
-**증상**: Feature가 많을 때 대시보드 생성 지연
-
-**해결**:
-```bash
-# 캐시 재구성
-/project:aiwf:feature_cache --rebuild
-
-# 특정 범위만 표시
-/project:aiwf:feature_dashboard --limit 50 --status active
-```
-
-#### 검색이 느림
-
-**증상**: Feature 검색 시 응답 지연
-
-**해결**:
-```bash
-# 인덱스 최적화
-/project:aiwf:feature_index --optimize
-
-# 검색 범위 제한
-/project:aiwf:feature_search "query" --status active --limit 20
-```
-
-### 데이터 복구
-
-#### Feature 파일 손상
-
-**증상**: Feature 파일을 열 수 없음
-
-**해결**:
-```bash
-# 백업에서 복구
-cp .aiwf/backups/FL001_*.md .aiwf/06_FEATURE_LEDGERS/active/
-
-# Git 히스토리에서 복구
-git checkout HEAD~1 -- .aiwf/06_FEATURE_LEDGERS/active/FL001_*.md
-```
-
-#### 인덱스 불일치
-
-**증상**: 인덱스와 실제 파일이 다름
-
-**해결**:
-```bash
-# 전체 인덱스 재구성
-/project:aiwf:feature_index --rebuild --verbose
-
-# 무결성 검사
-/project:aiwf:feature_validate --fix
-```
-
-## 고급 문제 해결
-
-### 디버깅 모드
-
-상세한 로그를 보려면:
-
-```bash
-# 디버그 모드 활성화
-export AIWF_DEBUG=true
-
-# 상세 로그와 함께 실행
-/project:aiwf:create_feature_ledger test_feature --verbose
-```
-
-### 로그 분석
-
-```bash
-# 오류 로그만 보기
-grep ERROR .aiwf/logs/feature_ledger.log
-
-# 특정 Feature 추적
-grep FL001 .aiwf/logs/feature_ledger.log | tail -20
-
-# 시간대별 분석
-grep "2025-07-09" .aiwf/logs/feature_ledger.log | grep ERROR
-```
-
-### 수동 수정
-
-직접 파일을 수정해야 할 때:
-
-1. **백업 생성**:
-   ```bash
-   cp -r .aiwf/06_FEATURE_LEDGERS .aiwf/06_FEATURE_LEDGERS.backup
-   ```
-
-2. **파일 수정**
-
-3. **검증**:
-   ```bash
-   /project:aiwf:feature_validate FL001
-   ```
-
-4. **인덱스 업데이트**:
-   ```bash
-   /project:aiwf:feature_index --update FL001
-   ```
-
-## 지원 받기
-
-### 1. 문서 참조
-- [User Guide](./FEATURE_LEDGER_USER_GUIDE.md)
-- [API Reference](./FEATURE_LEDGER_API_REFERENCE.md)
-- [System Overview](./FEATURE_LEDGER_SYSTEM_OVERVIEW.md)
-
-### 2. 커뮤니티
-- GitHub Issues: `https://github.com/aiwf/aiwf/issues`
-- Discord: AIWF 커뮤니티 채널
-
-### 3. 버그 리포트
-
-버그 발견 시:
-1. 재현 가능한 단계 기록
-2. 로그 파일 수집
-3. GitHub Issue 생성:
-   ```markdown
-   **버그 설명**: [간단한 설명]
-   **재현 단계**:
-   1. ...
-   2. ...
-   **예상 동작**: [예상했던 결과]
-   **실제 동작**: [실제 발생한 결과]
-   **로그**: [관련 로그 첨부]
-   ```
-
----
-
-*이 문서는 지속적으로 업데이트됩니다. 최신 버전은 [GitHub](https://github.com/aiwf/aiwf)에서 확인하세요.*

package/.aiwf/01_PROJECT_DOCS/FEATURE_LEDGER_SYSTEM_OVERVIEW.md

@@ -1,305 +0,0 @@
-# Feature Ledger System Overview
-
-## 시스템 개요
-
-Feature Ledger System은 AIWF의 핵심 구성 요소로, 프로젝트의 모든 기능 개발을 추적하고 관리합니다. 이 시스템은 개발 프로세스의 투명성을 높이고, 팀 협업을 강화하며, 프로젝트 진행 상황을 실시간으로 파악할 수 있게 합니다.
-
-## 아키텍처
-
-### 시스템 구성도
-
-```mermaid
-graph TB
-    subgraph "User Interface"
-        CLI[CLI Commands]
-        API[API Endpoints]
-    end
-    
-    subgraph "Core System"
-        FL[Feature Ledger Core]
-        VM[Validation Module]
-        SM[State Manager]
-        IM[Index Manager]
-    end
-    
-    subgraph "Integration Layer"
-        GI[Git Integration]
-        SI[Sprint Integration]
-        AI[AI Context Integration]
-    end
-    
-    subgraph "Storage"
-        FS[File System]
-        IDX[Index Files]
-        TMPL[Templates]
-    end
-    
-    CLI --> FL
-    API --> FL
-    FL --> VM
-    FL --> SM
-    FL --> IM
-    FL --> GI
-    FL --> SI
-    FL --> AI
-    VM --> FS
-    SM --> FS
-    IM --> IDX
-    GI --> FS
-    SI --> FS
-    AI --> FS
-```
-
-### 데이터 플로우
-
-```mermaid
-sequenceDiagram
-    participant User
-    participant CLI
-    participant FeatureLedger
-    participant StateManager
-    participant FileSystem
-    participant GitIntegration
-    
-    User->>CLI: create_feature_ledger
-    CLI->>FeatureLedger: parseCommand()
-    FeatureLedger->>StateManager: validateState()
-    StateManager->>FileSystem: checkExisting()
-    FileSystem-->>StateManager: notExists
-    StateManager->>FileSystem: createFeature()
-    FileSystem-->>StateManager: created
-    StateManager->>GitIntegration: createBranch()
-    GitIntegration-->>StateManager: branchCreated
-    StateManager-->>FeatureLedger: success
-    FeatureLedger-->>CLI: featureCreated
-    CLI-->>User: FL001 Created
-```
-
-### 상태 전이 다이어그램
-
-```mermaid
-stateDiagram-v2
-    [*] --> Active: create_feature
-    Active --> Paused: pause_feature
-    Active --> Completed: complete_feature
-    Active --> Archived: archive_feature
-    Paused --> Active: resume_feature
-    Paused --> Archived: archive_feature
-    Completed --> Archived: archive_feature
-    Archived --> [*]
-    
-    Active: Active\n- 개발 진행 중\n- 리소스 할당됨\n- 진행률 추적
-    Paused: Paused\n- 일시 중단\n- 리소스 재할당\n- 이유 문서화
-    Completed: Completed\n- 개발 완료\n- 테스트 통과\n- 문서 업데이트
-    Archived: Archived\n- 보관 상태\n- 읽기 전용\n- 히스토리 보존
-```
-
-## 핵심 구성 요소
-
-### 1. Feature Ledger Core
-
-시스템의 중앙 처리 엔진으로 다음 기능을 담당합니다:
-
-- **명령어 파싱**: 사용자 입력을 해석하고 검증
-- **비즈니스 로직**: Feature 생성, 업데이트, 상태 관리
-- **이벤트 처리**: 상태 변경 시 관련 시스템에 알림
-
-### 2. State Manager
-
-Feature의 생명주기를 관리합니다:
-
-- **상태 검증**: 유효한 상태 전환만 허용
-- **히스토리 추적**: 모든 상태 변경 기록
-- **일관성 보장**: 데이터 무결성 유지
-
-### 3. Index Manager
-
-빠른 검색과 조회를 위한 인덱싱 시스템:
-
-- **실시간 인덱싱**: Feature 변경 시 즉시 업데이트
-- **다중 인덱스**: ID, 상태, 태그, 담당자별 인덱스
-- **성능 최적화**: 캐싱 및 증분 업데이트
-
-### 4. Integration Modules
-
-#### Git Integration
-```mermaid
-graph LR
-    A[Feature] --> B{Git Action}
-    B --> C[Create Branch]
-    B --> D[Link Commit]
-    B --> E[Link PR]
-    C --> F[feature/FL001-name]
-    D --> G[Commit History]
-    E --> H[PR Status]
-```
-
-#### Sprint Integration
-- Feature와 Sprint/Task의 양방향 연결
-- 진행률 자동 계산
-- 마일스톤 추적
-
-#### AI Context Integration
-- 활성 Feature를 AI 컨텍스트에 포함
-- 토큰 효율을 위한 압축
-- 관련 Feature 자동 제안
-
-## 디렉토리 구조
-
-```
-.aiwf/06_FEATURE_LEDGERS/
-├── active/                    # 진행 중인 Feature
-│   ├── FL001_User_Auth.md
-│   └── FL002_Dashboard.md
-├── completed/                 # 완료된 Feature
-│   └── FL000_Initial.md
-├── archived/                  # 보관된 Feature
-│   └── FL_Archive_2025Q1/
-├── paused/                    # 일시 중단된 Feature
-│   └── FL003_Analytics.md
-├── FEATURE_LEDGER_INDEX.md    # 메인 인덱스
-├── FEATURE_SCHEMA.md          # 데이터 스키마
-├── FEATURE_STATE_DIAGRAM.md   # 상태 다이어그램
-├── FEATURE_INTEGRATION_GUIDE.md # 통합 가이드
-└── FEATURE_GIT_INTEGRATION.md # Git 통합 상세
-```
-
-## 데이터 모델
-
-### Feature Entity
-
-```yaml
-# 핵심 식별 정보
-feature_id: string (required, unique)
-title: string (required)
-status: enum [active, completed, paused, archived]
-created_date: date
-last_updated: datetime
-
-# 프로젝트 연결
-milestone: string
-sprint_ids: array<string>
-tasks: array<string>
-
-# 팀 정보
-assignee: string
-contributors: array<string>
-reviewers: array<string>
-
-# 분류
-priority: enum [critical, high, medium, low]
-complexity: enum [simple, moderate, complex]
-category: enum [feature, enhancement, bugfix, refactor]
-tags: array<string>
-
-# 시간 추적
-estimated_hours: number
-actual_hours: number
-estimated_completion: date
-actual_completion: date
-
-# Git 통합
-git_branch: string
-git_commits: array<commit_hash>
-pull_requests: array<pr_object>
-
-# 의존성
-depends_on: array<feature_id>
-blocks: array<feature_id>
-
-# 진행 상황
-progress_percentage: number (0-100)
-checklist_items_total: number
-checklist_items_completed: number
-
-# 리스크 관리
-risk_level: enum [low, medium, high]
-known_issues: array<string>
-mitigation_plans: array<string>
-```
-
-## 통합 지점
-
-### 1. AIWF 프로젝트 구조
-
-```mermaid
-graph TD
-    PM[Project Manifest] --> FL[Feature Ledgers]
-    MS[Milestones] --> FL
-    SP[Sprints] --> FL
-    TK[Tasks] --> FL
-    FL --> GH[GitHub]
-    FL --> AI[AI Context]
-    FL --> RP[Reports]
-```
-
-### 2. 외부 시스템 연동
-
-- **GitHub API**: PR, Issue, Commit 자동 연결
-- **CI/CD**: 빌드 상태와 Feature 진행률 연동
-- **프로젝트 관리 도구**: JIRA, Trello 등과 동기화 가능
-
-## 성능 고려사항
-
-### 인덱싱 성능
-
-- 인덱스 업데이트: < 100ms
-- Feature 검색: < 50ms (1000개 기준)
-- 대시보드 생성: < 1s
-
-### 확장성
-
-- Feature 수: 10,000개까지 테스트됨
-- 동시 사용자: 100명까지 지원
-- 파일 크기: 각 Feature 최대 1MB
-
-### 최적화 전략
-
-1. **증분 업데이트**: 전체 재생성 대신 변경된 부분만 업데이트
-2. **캐싱**: 자주 조회되는 데이터 메모리 캐싱
-3. **비동기 처리**: 무거운 작업은 백그라운드에서 처리
-
-## 보안 고려사항
-
-### 접근 제어
-
-- 파일 시스템 권한 기반
-- Git 권한과 연동
-- 민감 정보 마스킹
-
-### 감사 추적
-
-- 모든 변경사항 로깅
-- 사용자별 활동 추적
-- 변경 이력 보존
-
-## 향후 로드맵
-
-### Phase 1 (현재)
-- ✅ 기본 CRUD 기능
-- ✅ Git 통합
-- ✅ Sprint/Task 연동
-- ⏳ 대시보드 생성
-
-### Phase 2 (계획)
-- 📋 웹 UI 인터페이스
-- 📋 고급 검색 기능
-- 📋 자동화된 보고서
-- 📋 AI 기반 인사이트
-
-### Phase 3 (미래)
-- 🔮 다국어 지원
-- 🔮 플러그인 시스템
-- 🔮 외부 도구 통합 API
-- 🔮 모바일 앱 지원
-
-## 관련 문서
-
-- [API Reference](./FEATURE_LEDGER_API_REFERENCE.md)
-- [User Guide](./FEATURE_LEDGER_USER_GUIDE.md)
-- [Technical Specification](../02_REQUIREMENTS/M02_Context_Engineering_Enhancement/SPECS_Feature_Ledger_System.md)
-- [Integration Guide](../06_FEATURE_LEDGERS/FEATURE_INTEGRATION_GUIDE.md)
-
----
-
-*Feature Ledger System v1.0 - AIWF Project*