aiwf 0.3.1 → 0.3.2

package/.aiwf/06_FEATURE_LEDGERS/FEATURE_GIT_INTEGRATION.md

@@ -0,0 +1,314 @@
+# Feature Git Integration Specification
+
+This document defines how Features integrate with Git version control in AIWF.
+
+## Git Metadata Fields
+
+### Core Git Fields in Feature YAML
+
+```yaml
+# Git branch information
+git_branch: string              # Associated feature branch
+git_base_branch: string         # Base branch (usually main/master)
+
+# Commit tracking
+git_commits: [                  # List of related commits
+  {
+    hash: string,               # Commit SHA
+    message: string,            # Commit message
+    author: string,             # Author email
+    date: YYYY-MM-DD HH:MM,    # Commit timestamp
+    files_changed: integer,     # Number of files changed
+    insertions: integer,        # Lines added
+    deletions: integer          # Lines deleted
+  }
+]
+
+# Pull request tracking
+pull_requests: [                # Associated PRs
+  {
+    number: integer,            # PR number
+    title: string,              # PR title
+    status: string,             # open | merged | closed
+    url: string,                # Full PR URL
+    created_at: timestamp,      # PR creation time
+    merged_at: timestamp,       # PR merge time (if merged)
+    reviewers: [string],        # List of reviewers
+    labels: [string]            # PR labels
+  }
+]
+
+# Code metrics
+code_metrics: {
+  total_commits: integer,       # Total number of commits
+  total_lines_added: integer,   # Total insertions
+  total_lines_removed: integer, # Total deletions
+  files_impacted: integer,      # Unique files changed
+  first_commit: timestamp,      # First commit timestamp
+  last_commit: timestamp        # Most recent commit
+}
+```
+
+## Git Integration Workflow
+
+### 1. Feature Branch Creation
+
+When creating a new feature:
+
+```bash
+# Create feature in AIWF
+/project:aiwf:create_feature_ledger "User Authentication"
+# Returns: FL001
+
+# Create Git branch
+git checkout -b feature/FL001-user-authentication
+
+# Link branch to feature
+/project:aiwf:link_feature_branch FL001
+```
+
+### 2. Commit Tracking
+
+#### Automatic Commit Linking
+
+Commits mentioning the feature ID are automatically linked:
+
+```bash
+git commit -m "feat(FL001): implement JWT token generation"
+git commit -m "[FL001] add password hashing"
+git commit -m "FL001 - configure auth middleware"
+```
+
+#### Manual Commit Linking
+
+```bash
+/project:aiwf:link_feature_commit FL001 abc123def
+```
+
+### 3. Pull Request Integration
+
+#### PR Creation with Feature Link
+
+```bash
+# Create PR with feature reference
+gh pr create --title "[FL001] User Authentication Implementation" \
+  --body "Implements feature FL001: User Authentication System"
+
+# Auto-links to feature when title/body contains FL### pattern
+```
+
+#### PR Status Sync
+
+```bash
+# Sync PR status to feature
+/project:aiwf:sync_feature_pr FL001
+```
+
+## Commit Message Patterns
+
+### Feature ID Detection Patterns
+
+The following patterns in commit messages trigger auto-linking:
+
+1. `FL###` - Direct reference
+2. `[FL###]` - Bracketed reference
+3. `(FL###)` - Parenthetical reference
+4. `feat(FL###):` - Conventional commit format
+5. `FL###:` - Prefix format
+6. `#FL###` - Hash reference
+
+### Commit Message Guidelines
+
+```bash
+# Good examples
+git commit -m "feat(FL001): implement user registration endpoint"
+git commit -m "[FL001] add email validation to registration"
+git commit -m "fix(FL001): resolve token expiration bug"
+git commit -m "test(FL001): add unit tests for auth service"
+git commit -m "docs(FL001): update API documentation for auth endpoints"
+
+# Conventional commit types for features
+feat(FL###):     # New feature implementation
+fix(FL###):      # Bug fixes in feature
+test(FL###):     # Tests for feature
+docs(FL###):     # Documentation for feature
+refactor(FL###): # Code refactoring
+perf(FL###):     # Performance improvements
+style(FL###):    # Code style changes
+```
+
+## Git Hooks Integration
+
+### Pre-commit Hook
+
+```bash
+#!/bin/bash
+# .git/hooks/pre-commit
+
+# Check if commits reference a feature
+feature_id=$(git diff --cached --name-only | xargs grep -l "FL[0-9]\{3\}" | head -1)
+
+if [ -n "$feature_id" ]; then
+    echo "Feature reference detected. Updating feature ledger..."
+    /project:aiwf:update_feature_activity "$feature_id"
+fi
+```
+
+### Post-commit Hook
+
+```bash
+#!/bin/bash
+# .git/hooks/post-commit
+
+# Extract feature ID from commit message
+commit_msg=$(git log -1 --pretty=%B)
+feature_id=$(echo "$commit_msg" | grep -o "FL[0-9]\{3\}" | head -1)
+
+if [ -n "$feature_id" ]; then
+    # Link commit to feature
+    commit_hash=$(git rev-parse HEAD)
+    /project:aiwf:link_feature_commit "$feature_id" "$commit_hash"
+fi
+```
+
+### Post-merge Hook
+
+```bash
+#!/bin/bash
+# .git/hooks/post-merge
+
+# Update feature status when PR is merged
+branch_name=$(git rev-parse --abbrev-ref HEAD)
+if [[ "$branch_name" == "main" || "$branch_name" == "master" ]]; then
+    # Extract feature ID from merged branch
+    merged_branch=$(git reflog -1 | grep -o "feature/FL[0-9]\{3\}[^[:space:]]*")
+    if [ -n "$merged_branch" ]; then
+        feature_id=$(echo "$merged_branch" | grep -o "FL[0-9]\{3\}")
+        /project:aiwf:update_feature_status "$feature_id" "completed"
+    fi
+fi
+```
+
+## Git Commands for Feature Management
+
+### Link Current Branch to Feature
+```bash
+/project:aiwf:link_feature_branch FL001
+```
+
+### Import Commit History
+```bash
+/project:aiwf:import_feature_commits FL001 --since="2025-07-01"
+```
+
+### Generate Feature Changelog
+```bash
+/project:aiwf:feature_changelog FL001
+```
+
+Output:
+```markdown
+# Feature FL001 Changelog
+
+## Commits (15 total)
+- abc123d feat(FL001): implement JWT token generation (2025-07-08)
+- def456e [FL001] add password hashing (2025-07-09)
+- ghi789f fix(FL001): resolve token expiration bug (2025-07-10)
+
+## Pull Requests (2 total)
+- PR #42: [FL001] User Authentication Implementation (merged)
+- PR #45: [FL001] Fix token validation (open)
+
+## Code Impact
+- Files changed: 23
+- Lines added: 1,245
+- Lines removed: 89
+- First commit: 2025-07-08
+- Last activity: 2025-07-10
+```
+
+### Feature Git Status
+```bash
+/project:aiwf:feature_git_status FL001
+```
+
+Output:
+```
+Feature: FL001 - User Authentication System
+Branch: feature/FL001-user-authentication
+Status: 5 commits ahead of main
+Uncommitted changes: 2 files
+Open PRs: 1
+```
+
+## Automation Rules
+
+### 1. Branch Naming Convention
+- Pattern: `feature/FL###-descriptive-name`
+- Auto-created when feature is created
+- Validated before commits
+
+### 2. Commit Aggregation
+- Commits are aggregated daily
+- Metrics updated every 6 hours
+- Full history preserved
+
+### 3. PR Auto-Updates
+- PR status synced on webhook
+- Feature progress updated on merge
+- Reviewers added to contributors
+
+### 4. Completion Triggers
+- Feature marked complete when PR merged to main
+- Notification sent to stakeholders
+- Metrics finalized
+
+## Git Integration Metrics
+
+### Feature Velocity Metrics
+- Average commits per feature
+- Time from first commit to merge
+- Code churn rate
+- Review turnaround time
+
+### Quality Metrics
+- Test coverage delta
+- Code review comments
+- Bug fix ratio
+- Refactoring frequency
+
+### Team Metrics
+- Commits per developer
+- Review participation
+- Feature ownership distribution
+- Collaboration patterns
+
+## Best Practices
+
+1. **One Feature, One Branch**: Each feature should have dedicated branch
+2. **Atomic Commits**: Make small, focused commits with clear messages
+3. **Reference Features**: Always include feature ID in commit messages
+4. **Regular Sync**: Run sync commands after significant changes
+5. **Clean History**: Squash commits before merging for clarity
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Missing Commits**: Run import command to catch up
+2. **Broken Links**: Use repair command to fix references
+3. **Orphaned Branches**: Clean up after feature completion
+4. **Sync Delays**: Check webhook configuration
+
+### Repair Commands
+
+```bash
+# Repair feature-git links
+/project:aiwf:repair_feature_git FL001
+
+# Resync all features
+/project:aiwf:resync_all_features
+
+# Clean orphaned branches
+/project:aiwf:clean_feature_branches
+```

package/.aiwf/06_FEATURE_LEDGERS/FEATURE_INTEGRATION_GUIDE.md

@@ -0,0 +1,227 @@
+# Feature Integration Guide
+
+This document describes how Features integrate with Milestones, Sprints, and Tasks in AIWF.
+
+## Integration Architecture
+
+```
+Milestone (M##)
+    └── Features (FL###)
+         └── Sprints (S##_M##)
+              └── Tasks (T##_S##)
+```
+
+## Milestone Integration
+
+### Linking Features to Milestones
+
+Each feature is associated with exactly one milestone through the `milestone` field in the YAML frontmatter.
+
+```yaml
+milestone: M02  # Required field
+```
+
+### Milestone Progress Calculation
+
+Milestone progress is calculated based on:
+- Number of completed features vs total features
+- Weighted by feature complexity
+- Formula: `Σ(completed_features * complexity_weight) / Σ(all_features * complexity_weight)`
+
+### Complexity Weights
+- `simple`: 1.0
+- `moderate`: 2.0
+- `complex`: 3.0
+
+## Sprint Integration
+
+### Multi-Sprint Features
+
+Features often span multiple sprints. The `sprint_ids` array tracks all related sprints:
+
+```yaml
+sprint_ids: [S01_M02, S02_M02, S03_M02]
+```
+
+### Sprint Assignment Rules
+
+1. Features are assigned to sprints during sprint planning
+2. A feature can be active in multiple sprints
+3. Sprint progress includes partial feature completion
+
+### Sprint Progress Tracking
+
+For features spanning multiple sprints:
+- Track `progress_percentage` at feature level
+- Calculate sprint-specific progress based on completed tasks
+- Update feature progress after each sprint
+
+## Task Integration
+
+### Linking Tasks to Features
+
+Tasks reference their parent feature:
+
+```yaml
+# In task file
+feature_id: FL001
+```
+
+Features track their child tasks:
+
+```yaml
+# In feature file
+tasks: [T01_S01, T02_S01, T05_S02]
+```
+
+### Task Completion Impact
+
+When a task is completed:
+1. Update feature's task list
+2. Recalculate feature progress
+3. Update sprint progress
+4. Trigger milestone progress update
+
+### Progress Calculation
+
+Feature progress based on tasks:
+```
+progress = (completed_tasks / total_tasks) * 100
+```
+
+## Bidirectional Sync Mechanisms
+
+### 1. Feature Creation
+```
+Create Feature → Update Milestone → Link to Current Sprint
+```
+
+### 2. Task Creation
+```
+Create Task → Link to Feature → Update Feature Task List
+```
+
+### 3. Sprint Planning
+```
+Assign Features to Sprint → Update Feature sprint_ids → Update Sprint Scope
+```
+
+### 4. Status Updates
+```
+Complete Task → Update Feature Progress → Update Sprint Progress → Update Milestone Progress
+```
+
+## Command Integration
+
+### Create Feature with Milestone
+```bash
+/project:aiwf:create_feature_ledger "User Authentication" --milestone M02
+```
+
+### Link Feature to Sprint
+```bash
+/project:aiwf:link_feature_sprint FL001 S02_M02
+```
+
+### Update Feature from Task Completion
+```bash
+/project:aiwf:complete_task T01_S01
+# Automatically updates FL001 progress
+```
+
+## Data Consistency Rules
+
+### 1. Referential Integrity
+- Milestone must exist before feature assignment
+- Sprint must belong to the same milestone
+- Tasks must belong to linked sprints
+
+### 2. Status Consistency
+- Feature cannot be "completed" if tasks are incomplete
+- Milestone cannot be "completed" if features are incomplete
+- Archived features are excluded from progress calculations
+
+### 3. Progress Synchronization
+- Task completion triggers feature progress update
+- Feature progress updates trigger milestone recalculation
+- All updates are timestamped for audit trail
+
+## Integration Queries
+
+### Find Features by Milestone
+```bash
+/project:aiwf:list_features --milestone M02
+```
+
+### Find Features by Sprint
+```bash
+/project:aiwf:list_features --sprint S01_M02
+```
+
+### Feature Impact Analysis
+```bash
+/project:aiwf:feature_impact FL001
+# Shows: Related tasks, sprints, blocking features
+```
+
+## Reporting Integration
+
+### Milestone Report includes:
+- Feature count by status
+- Overall progress percentage
+- Feature complexity distribution
+- Estimated vs actual timeline
+
+### Sprint Report includes:
+- Active features
+- Feature progress within sprint
+- Task completion rate
+- Velocity metrics
+
+### Feature Report includes:
+- Task breakdown
+- Sprint allocation
+- Time tracking
+- Dependency graph
+
+## Best Practices
+
+1. **Plan Features First**: Define features before creating tasks
+2. **Update Regularly**: Keep progress percentages current
+3. **Cross-Reference**: Ensure bidirectional links are maintained
+4. **Review Dependencies**: Check for blocked features before sprint planning
+5. **Archive Completed**: Move completed features to maintain performance
+
+## Automated Workflows
+
+### On Feature Creation:
+1. Generate unique feature ID
+2. Link to active milestone
+3. Create in active sprint (if in progress)
+4. Initialize progress tracking
+
+### On Task Completion:
+1. Update feature task list
+2. Recalculate feature progress
+3. Check if feature is complete
+4. Propagate to milestone
+
+### On Sprint Close:
+1. Review feature progress
+2. Move incomplete features to next sprint
+3. Archive completed features
+4. Generate sprint report
+
+## Error Handling
+
+### Common Issues:
+1. **Orphaned Features**: Features without milestone
+2. **Broken References**: Tasks referencing non-existent features
+3. **Circular Dependencies**: Features depending on each other
+4. **Stale Progress**: Outdated progress percentages
+
+### Resolution:
+- Regular integrity checks
+- Automated fixing scripts
+- Manual review process
+- Audit trail for changes

package/.aiwf/06_FEATURE_LEDGERS/FEATURE_LEDGER_INDEX.md

@@ -0,0 +1,23 @@
+# Feature Ledger 인덱스
+
+마지막 업데이트: 2025-07-10T02:37:15.882Z
+
+## 활성 Features
+
+| ID | 제목 | 상태 | 우선순위 | 진행률 | 업데이트 |
+|----|------|------|----------|--------|----------|
+| FL001 | User Authentication System | active | medium | 0% | 2025-07-10 |
+| FL002 | User Authentication System | active | medium | 0% | 2025-07-10 |
+
+## 보관된 Features
+
+| ID | 제목 | 완료일 |
+|----|------|--------|
+
+## 통계
+
+- 총 Features: 2
+- 활성: 2
+- 완료: 0
+- 일시 중지: 0
+- 보관됨: 0