moai-adk 0.9.1__py3-none-any.whl → 0.10.1__py3-none-any.whl

moai_adk/templates/.claude/hooks/alfred/shared/core/project.py

@@ -16,6 +16,58 @@ from typing import Any
 CACHE_DIR_NAME = ".moai/cache"
 
 
+def find_project_root(start_path: str | Path = ".") -> Path:
+    """Find MoAI-ADK project root by searching upward for .moai/config.json
+
+    Traverses up the directory tree until it finds .moai/config.json or CLAUDE.md,
+    which indicates the project root. This ensures cache and other files are
+    always created in the correct location, regardless of where hooks execute.
+
+    Args:
+        start_path: Starting directory (default: current directory)
+
+    Returns:
+        Project root Path. If not found, returns start_path as absolute path.
+
+    Examples:
+        >>> find_project_root(".")
+        Path("/Users/user/my-project")
+        >>> find_project_root(".claude/hooks/alfred")
+        Path("/Users/user/my-project")  # Found root 3 levels up
+
+    Notes:
+        - Searches for .moai/config.json first (most reliable)
+        - Falls back to CLAUDE.md if config.json not found
+        - Max depth: 10 levels up (prevent infinite loop)
+        - Returns absolute path for consistency
+
+    TDD History:
+        - RED: 4 test scenarios (root, nested, not found, symlinks)
+        - GREEN: Minimal upward search with .moai/config.json detection
+        - REFACTOR: Add CLAUDE.md fallback, max depth limit, absolute path return
+    """
+    current = Path(start_path).resolve()
+    max_depth = 10  # Prevent infinite loop
+
+    for _ in range(max_depth):
+        # Check for .moai/config.json (primary indicator)
+        if (current / ".moai" / "config.json").exists():
+            return current
+
+        # Check for CLAUDE.md (secondary indicator)
+        if (current / "CLAUDE.md").exists():
+            return current
+
+        # Move up one level
+        parent = current.parent
+        if parent == current:  # Reached filesystem root
+            break
+        current = parent
+
+    # Not found - return start_path as absolute
+    return Path(start_path).resolve()
+
+
 class TimeoutError(Exception):
     """Signal-based timeout exception"""
     pass
@@ -246,7 +298,7 @@ def count_specs(cwd: str) -> dict[str, int]:
     Counts the number of SPECs with status: completed.
 
     Args:
-        cwd: Project root directory path
+        cwd: Project root directory path (or any subdirectory, will search upward)
 
     Returns:
         SPEC progress dictionary. Includes the following keys:
@@ -264,15 +316,19 @@ def count_specs(cwd: str) -> dict[str, int]:
 
     Notes:
         - SPEC File Location: .moai/specs/SPEC-{ID}/spec.md
-        - Completion condition: Include “status: completed” in YAML front matter
+        - Completion condition: Include "status: completed" in YAML front matter
         - If parsing fails, the SPEC is considered incomplete.
+        - Automatically finds project root to locate .moai/specs/
 
     TDD History:
         - RED: 5 items scenario test (0/0, 2/5, 5/5, no directory, parsing error)
         - GREEN: SPEC search with Path.iterdir(), YAML parsing implementation
         - REFACTOR: Strengthened exception handling, improved percentage calculation safety
+        - UPDATE: Add project root detection for consistent path resolution
     """
-    specs_dir = Path(cwd) / ".moai" / "specs"
+    # Find project root to ensure we read specs from correct location
+    project_root = find_project_root(cwd)
+    specs_dir = project_root / ".moai" / "specs"
 
     if not specs_dir.exists():
         return {"completed": 0, "total": 0, "percentage": 0}
@@ -316,7 +372,7 @@ def get_project_language(cwd: str) -> str:
     """Determine the primary project language (prefers config.json).
 
     Args:
-        cwd: Project root directory.
+        cwd: Project root directory (or any subdirectory, will search upward).
 
     Returns:
         Language string in lower-case.
@@ -324,8 +380,11 @@ def get_project_language(cwd: str) -> str:
     Notes:
         - Reads ``.moai/config.json`` first for a quick answer.
         - Falls back to ``detect_language`` if configuration is missing.
+        - Automatically finds project root to locate .moai/config.json
     """
-    config_path = Path(cwd) / ".moai" / "config.json"
+    # Find project root to ensure we read config from correct location
+    project_root = find_project_root(cwd)
+    config_path = project_root / ".moai" / "config.json"
     if config_path.exists():
         try:
             config = json.loads(config_path.read_text())
@@ -336,8 +395,8 @@ def get_project_language(cwd: str) -> str:
             # Fall back to detection on parse errors
             pass
 
-    # Fall back to the original language detection routine
-    return detect_language(cwd)
+    # Fall back to the original language detection routine (use project root)
+    return detect_language(str(project_root))
 
 
 # @CODE:CONFIG-INTEGRATION-001
@@ -382,7 +441,9 @@ def get_version_check_config(cwd: str) -> dict[str, Any]:
         "cache_ttl_hours": 24
     }
 
-    config_path = Path(cwd) / ".moai" / "config.json"
+    # Find project root to ensure we read config from correct location
+    project_root = find_project_root(cwd)
+    config_path = project_root / ".moai" / "config.json"
     if not config_path.exists():
         return defaults
 
@@ -509,36 +570,42 @@ def is_major_version_change(current: str, latest: str) -> bool:
 def get_package_version_info(cwd: str = ".") -> dict[str, Any]:
     """Check MoAI-ADK current and latest version with caching and offline support.
 
+    ⭐ CRITICAL GUARANTEE: This function ALWAYS returns the current installed version.
+    Network failures, cache issues, and timeouts NEVER result in "unknown" version.
+
     Execution flow:
-    1. Try to load from cache (< 50ms)
-    2. If cache invalid, check network
-    3. If network available, query PyPI
-    4. If network unavailable, return current version only
-    5. Save result to cache for next time
+    1. Get current installed version (ALWAYS succeeds) ← CRITICAL
+    2. Build minimal result with current version
+    3. Try to load from cache (< 50ms) - optional enhancement
+    4. If cache valid, return cached latest info
+    5. If cache invalid/miss, optionally query PyPI - optional enhancement
+    6. Save result to cache for next time - optional
 
     Args:
         cwd: Project root directory (for cache location)
 
     Returns:
         dict with keys:
-            - "current": Current installed version
-            - "latest": Latest version available on PyPI
+            - "current": Current installed version (ALWAYS valid, never empty)
+            - "latest": Latest version available on PyPI (may be "unknown")
             - "update_available": Boolean indicating if update is available
             - "upgrade_command": Recommended upgrade command (if update available)
-            - "release_notes_url": URL to release notes (Phase 3)
-            - "is_major_update": Boolean indicating major version change (Phase 3)
+            - "release_notes_url": URL to release notes
+            - "is_major_update": Boolean indicating major version change
 
-    Note:
-        - Cache hit (< 24 hours): Returns in ~20ms, no network access
-        - Cache miss + online: Query PyPI (1s timeout), cache result
-        - Cache miss + offline: Return current version only (~100ms)
-        - Offline + cached: Return from cache in ~20ms
+    Guarantees:
+        - Cache hit (< 24 hours): Returns in ~20ms, no network access ✓
+        - Cache miss + online: Query PyPI (1s timeout), cache result ✓
+        - Cache miss + offline: Return current version only (~100ms) ✓
+        - Network timeout: Returns current + "unknown" latest (~50ms) ✓
+        - Any exception: Always returns current version ✓
 
     TDD History:
         - RED: 5 test scenarios (network detection, cache integration, offline mode)
         - GREEN: Integrate VersionCache with network detection
         - REFACTOR: Extract cache directory constant, improve error handling
         - Phase 3: Add release_notes_url and is_major_update fields (@CODE:VERSION-INTEGRATE-FIELDS-001)
+        - Phase 4: CRITICAL FIX - Always guarantee current version return (@CODE:VERSION-ALWAYS-VALID-001)
     """
     import importlib.util
     import urllib.error
@@ -560,8 +627,13 @@ def get_package_version_info(cwd: str = ".") -> dict[str, Any]:
         # Graceful degradation: skip caching on import errors
         VersionCache = None
 
-    # 1. Initialize cache (skip if VersionCache couldn't be imported)
-    cache_dir = Path(cwd) / CACHE_DIR_NAME
+    # 1. Find project root (ensure cache is always in correct location)
+    # This prevents creating .moai/cache in wrong locations when hooks run
+    # from subdirectories like .claude/hooks/alfred/
+    project_root = find_project_root(cwd)
+
+    # 2. Initialize cache (skip if VersionCache couldn't be imported)
+    cache_dir = project_root / CACHE_DIR_NAME
     version_cache = VersionCache(cache_dir) if VersionCache else None
 
     # 2. Get current installed version first (needed for cache validation)
@@ -672,6 +744,7 @@ def get_package_version_info(cwd: str = ".") -> dict[str, Any]:
 
 
 __all__ = [
+    "find_project_root",
     "detect_language",
     "get_git_info",
     "count_specs",

moai_adk/templates/.git-hooks/pre-push

@@ -0,0 +1,143 @@
+#!/bin/bash
+
+# MoAI-ADK GitFlow Main Branch Control Hook
+# Purpose: Enforce GitFlow in team mode, advisory in personal mode
+# Enforces: Strict team workflow, flexible personal development
+#
+# This hook runs before any git push operation:
+# Team Mode:   Blocks direct main/master push (non-develop), requires confirmation for develop→main
+# Personal Mode: Advisory warnings, allows flexibility
+#
+# Exit codes:
+# 0 - Push allowed
+# 1 - Push blocked (team mode violation or user declined)
+
+# Check team mode from .moai/config.json
+is_team_mode() {
+    if [ -f ".moai/config.json" ]; then
+        # Check if mode is "team"
+        grep -q '"mode".*:.*"team"' ".moai/config.json" 2>/dev/null
+        return $?
+    fi
+    return 1
+}
+
+# Colors for output
+RED='\033[0;31m'
+YELLOW='\033[1;33m'
+GREEN='\033[0;32m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+TEAM_MODE=false
+is_team_mode && TEAM_MODE=true
+
+# Read from stdin (git sends remote, local ref info)
+# Format: <local ref> <local oid> <remote ref> <remote oid>
+while read local_ref local_oid remote_ref remote_oid; do
+    # Extract the remote branch name from the reference
+    # remote_ref format: refs/heads/main
+    remote_branch=$(echo "$remote_ref" | sed 's|refs/heads/||')
+    local_branch=$(echo "$local_ref" | sed 's|refs/heads/||')
+
+    # Check if attempting to push to main branch
+    if [ "$remote_branch" = "main" ] || [ "$remote_branch" = "master" ]; then
+        # Get the current branch to determine if this is the develop branch
+        current_branch=$(git rev-parse --abbrev-ref HEAD)
+
+        # TEAM MODE ENFORCEMENT
+        if [ "$TEAM_MODE" = true ]; then
+            # Block non-develop, non-release branches from pushing to main
+            if [ "$local_branch" != "develop" ] && [ "${local_branch#release/}" = "$local_branch" ]; then
+                echo ""
+                echo -e "${RED}❌ BLOCKED: Non-standard GitFlow in TEAM MODE${NC}"
+                echo ""
+                echo -e "${BLUE}Current branch: ${local_branch}${NC}"
+                echo -e "${BLUE}Target branch: ${remote_branch}${NC}"
+                echo ""
+                echo "🚀 Correct GitFlow workflow for TEAM MODE:"
+                echo "  1. Work on feature/SPEC-{ID} branch (created from develop)"
+                echo "  2. Push to feature/SPEC-{ID} and create PR to develop"
+                echo "  3. Code review & merge into develop"
+                echo "  4. When develop is stable, create PR from develop to main"
+                echo "  5. Release manager merges develop → main with tag"
+                echo ""
+                echo -e "${RED}⚠️  Push to ${remote_branch} blocked in team mode${NC}"
+                echo ""
+                exit 1
+            fi
+
+            # For develop → main or release/* → main, ask for confirmation
+            if [ "$local_branch" = "develop" ] || [ "${local_branch#release/}" != "$local_branch" ]; then
+                echo ""
+                echo -e "${YELLOW}⚠️  TEAM MODE: Pushing ${local_branch} → ${remote_branch}${NC}"
+                echo ""
+                echo "📋 Summary:"
+                echo "  • Source branch: ${local_branch}"
+                echo "  • Target branch: ${remote_branch}"
+                echo "  • Mode: TEAM MODE (strict enforcement)"
+                echo ""
+                read -p "❓ Are you sure you want to push ${local_branch} to ${remote_branch}? (y/n) " -n 1 -r
+                echo ""
+                if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+                    echo -e "${RED}✓ Push cancelled by user${NC}"
+                    exit 1
+                fi
+            fi
+        fi
+
+        # PERSONAL MODE: Advisory warnings (allow all pushes)
+        if [ "$TEAM_MODE" = false ]; then
+            # Advisory: recommend develop -> main workflow
+            if [ "$local_branch" != "develop" ] && [ "${local_branch#release/}" = "$local_branch" ]; then
+                echo ""
+                echo -e "${YELLOW}⚠️  ADVISORY: Non-standard GitFlow detected${NC}"
+                echo ""
+                echo -e "${BLUE}Current branch: ${local_branch}${NC}"
+                echo -e "${BLUE}Target branch: ${remote_branch}${NC}"
+                echo ""
+                echo "Recommended GitFlow workflow:"
+                echo "  1. Work on feature/SPEC-{ID} branch (created from develop)"
+                echo "  2. Push to feature/SPEC-{ID} and create PR to develop"
+                echo "  3. Merge into develop after code review"
+                echo "  4. When develop is stable, create PR from develop to main"
+                echo "  5. Release manager merges develop -> main with tag"
+                echo ""
+                echo -e "${GREEN}✓ Push will proceed (personal mode - flexibility enabled)${NC}"
+                echo ""
+            fi
+
+            # Check for delete operation
+            if [ "$local_oid" = "0000000000000000000000000000000000000000" ]; then
+                echo ""
+                echo -e "${RED}⚠️  WARNING: Attempting to delete main branch${NC}"
+                echo ""
+                echo -e "${YELLOW}This operation is highly discouraged.${NC}"
+                echo -e "${GREEN}✓ Push will proceed (personal mode - flexibility enabled)${NC}"
+                echo ""
+            fi
+
+            # Check for force push attempts to main
+            if [ "$remote_branch" = "main" ] || [ "$remote_branch" = "master" ]; then
+                # Check if remote_oid exists (non-zero means we're trying to update existing ref)
+                if [ "$remote_oid" != "0000000000000000000000000000000000000000" ]; then
+                    # Verify this is a fast-forward merge (no force push)
+                    if ! git merge-base --is-ancestor "$remote_oid" "$local_oid" 2>/dev/null; then
+                        echo ""
+                        echo -e "${YELLOW}⚠️  ADVISORY: Force-push to main branch detected${NC}"
+                        echo ""
+                        echo "Recommended approach:"
+                        echo "  - Use GitHub PR with proper code review"
+                        echo "  - Ensure changes are merged via fast-forward"
+                        echo ""
+                        echo -e "${GREEN}✓ Push will proceed (personal mode - flexibility enabled)${NC}"
+                        echo ""
+                    fi
+                fi
+            fi
+        fi
+    fi
+done
+
+# All checks passed (or advisory warnings shown)
+exit 0

moai_adk/templates/.github/workflows/tag-validation.yml

@@ -17,6 +17,10 @@ jobs:
     # Skip validation on draft PRs (allow WIP)
     if: github.event.pull_request.draft == false || github.event_name == 'push'
 
+    permissions:
+      contents: read
+      pull-requests: write
+
     steps:
       - name: Checkout code
         uses: actions/checkout@v4

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

@@ -1,36 +1,40 @@
-# GitFlow Advisory Policy
+# GitFlow Protection Policy
 
-**Document ID**: @DOC:GITFLOW-POLICY-001  
-**Published**: 2025-10-17  
-**Status**: Advisory (recommended, not enforced)  
+**Document ID**: @DOC:GITFLOW-POLICY-ALIAS
+**Published**: 2025-10-17
+**Updated**: 2025-10-29
+**Status**: **Enforced via GitHub Branch Protection** (v0.8.3+)
 **Scope**: Personal and Team modes
 
 ---
 
 ## Overview
 
-MoAI-ADK **recommends** a GitFlow-inspired workflow. This policy shares best practices while letting teams adapt them as needed.
+MoAI-ADK **enforces** a GitFlow-inspired workflow through GitHub Branch Protection. As of v0.8.3, the `main` branch is protected and requires Pull Requests for all changes, including from administrators.
 
-## Key Recommendations
+**What Changed**: Previously (v0.3.5-v0.8.2), we used an advisory approach with warnings. Now we enforce proper GitFlow to ensure code quality and prevent accidental direct pushes to main.
 
-### 1. Main Branch Access (Recommended)
+## Key Requirements (Enforced)
 
-| Recommendation | Summary | Enforcement |
-|----------------|---------|-------------|
-| **Merge via develop** | Prefer merging `develop` into `main` | Advisory ⚠️ |
-| **Feature branches off develop** | Branch from `develop` and raise PRs back to `develop` | Advisory ⚠️ |
-| **Release process** | Release flow: `develop` → `main` (release engineer encouraged) | Advisory ⚠️ |
-| **Force push** | Warn when force-pushing, but allow it | Warning ⚠️ |
-| **Direct push** | Warn on direct pushes to `main`, but allow them | Warning ⚠️ |
+### 1. Main Branch Access (Enforced)
 
-### 2. Git Workflow (Recommended)
+| Requirement | Summary | Enforcement |
+|-------------|---------|-------------|
+| **Merge via develop** | MUST merge `develop` into `main` | ✅ Enforced |
+| **Feature branches off develop** | MUST branch from `develop` and raise PRs back to `develop` | ✅ Enforced |
+| **Release process** | Release flow: `develop` → `main` (PR required) | ✅ Enforced |
+| **Force push** | Blocked on `main` | ✅ Blocked |
+| **Direct push** | Blocked on `main` (PR required) | ✅ Blocked |
+
+### 2. Git Workflow (Required)
 
 ```
 ┌─────────────────────────────────────────────────────────┐
-│                RECOMMENDED GITFLOW                      │
+│                ENFORCED GITFLOW                         │
+│         (GitHub Branch Protection Active)               │
 └─────────────────────────────────────────────────────────┘
 
-        develop (recommended base branch)
+        develop (required base branch)
           ↑     ↓
     ┌─────────────────┐
     │                 │
@@ -46,13 +50,15 @@ feature/SPEC-{ID}   [PR: feature -> develop]
          │   (release manager prepares)
          ↓
     [PR: develop -> main]
+    [Code review + approval REQUIRED]
+    [All discussions resolved]
     [CI/CD validation]
     [tag creation]
          ↓
-       main (release)
+       main (protected release)
 ```
 
-**Flexibility**: Direct pushes to `main` are still possible, but the workflow above is preferred.
+**Enforcement**: Direct pushes to `main` are **blocked** via GitHub Branch Protection. All changes must go through Pull Requests.
 
 ## Technical Implementation
 
@@ -156,18 +162,29 @@ git push origin v1.0.0
 
 ## Policy Modes
 
-### Strict Mode (Legacy, Currently Disabled)
+### Strict Mode (Active, v0.8.3+) ✅ ENFORCED
+
+**GitHub Branch Protection Enabled**:
+- ✅ **enforce_admins: true** - Administrators must follow all rules
+- ✅ **required_pull_request_reviews** - 1 approval required
+- ✅ **required_conversation_resolution** - All discussions must be resolved
+- ✅ **Block direct pushes to `main`** - PR required for all users
+- ✅ **Block force pushes** - Prevents history rewriting
+- ✅ **Block branch deletion** - Protects main from accidental deletion
 
-- ❌ Block direct pushes to `main`
-- ❌ Block force pushes
-- ❌ Block merges into `main` from any branch other than `develop`
+**What This Means**:
+- ❌ No one (including admins) can push directly to `main`
+- ✅ All changes must go through Pull Requests
+- ✅ PRs require code review approval
+- ✅ All code discussions must be resolved before merge
+- ✅ Enforces proper GitFlow: feature → develop → main
 
-### Advisory Mode (Active, v0.3.5+)
+### Advisory Mode (Legacy, v0.3.5 - v0.8.2)
 
-- ⚠️ Warn but allow direct pushes to `main`
-- ⚠️ Warn but allow force pushes
-- ⚠️ Recommend best practices while preserving flexibility
-- ✅ Respect user judgment
+- ⚠️ Warned but allowed direct pushes to `main`
+- ⚠️ Warned but allowed force pushes
+- ⚠️ Recommended best practices while preserving flexibility
+- ❌ **Deprecated** - Replaced by Strict Mode for better quality control
 
 ---
 
@@ -202,8 +219,98 @@ A: Yes. Expect an advisory warning, yet the push continues.
 **Q: Can I disable the hook entirely?**  
 A: Yes. Remove `.git/hooks/pre-push` or strip its execute permission.
 
-**Q: Why switch to Advisory Mode?**  
-A: To promote best practices while respecting contributor flexibility and judgment.
+**Q: Why switch to Advisory Mode?**
+A: Advisory Mode was used in v0.3.5-v0.8.2. As of v0.8.3, we've switched to Strict Mode with GitHub Branch Protection for better quality control.
+
+**Q: What if develop falls behind main?**
+A: This can happen when hotfixes or releases go directly to main. Regularly sync main → develop to prevent divergence. See "Maintaining develop-main Sync" section below.
+
+**Q: Can I bypass branch protection in emergencies?**
+A: No. Even administrators must follow the PR process. For true emergencies, temporarily disable protection via GitHub Settings (requires admin access), but re-enable immediately after.
+
+---
+
+## Maintaining develop-main Sync
+
+### ⚠️ Critical Rule: develop Must Stay Current
+
+**Problem**: When main receives direct commits (hotfixes, emergency releases) without syncing back to develop, GitFlow breaks:
+
+```
+❌ BAD STATE:
+develop: 3 commits ahead, 29 commits behind main
+- develop has outdated dependencies
+- New features branch from old code
+- Merge conflicts multiply over time
+```
+
+### Signs of Drift
+
+Monitor for these warnings:
+- `git status` shows "Your branch is X commits behind main"
+- Feature branches conflict with main during PR
+- CI/CD failures due to dependency mismatches
+- Version numbers in develop don't match main
+
+### Recovery Procedure
+
+When develop falls behind main:
+
+1. **Assess the Gap**
+   ```bash
+   git log --oneline develop..main  # Commits in main but not develop
+   git log --oneline main..develop  # Commits in develop but not main
+   ```
+
+2. **Sync Strategy: Merge main into develop (Recommended)**
+   ```bash
+   git checkout develop
+   git pull origin develop        # Get latest develop
+   git merge main                 # Merge main into develop
+   # Resolve conflicts if any (prefer main for version/config files)
+   git push origin develop
+   ```
+
+3. **Emergency Only: Reset develop to main (Destructive)**
+   ```bash
+   # ⚠️ ONLY if develop's unique commits are unwanted
+   git checkout develop
+   git reset --hard main
+   git push origin develop --force
+   ```
+
+### Prevention: Regular Sync Schedule
+
+**After every main release** (REQUIRED):
+```bash
+# Immediately after merging develop → main:
+git checkout develop
+git merge main
+git push origin develop
+```
+
+**Weekly maintenance** (for active projects):
+```bash
+# Every Monday morning:
+git checkout develop
+git pull origin main
+git push origin develop
+```
+
+### Real-World Case Study (2025-10-29)
+
+**Situation**: develop was 29 commits behind main due to:
+- v0.8.2, v0.8.3 released directly to main
+- No reverse sync to develop
+- Feature branches contained outdated code
+
+**Resolution**:
+- Merged main → develop (14 file conflicts)
+- Resolved conflicts prioritizing main's versions
+- TAG validation bypassed for merge commit
+- Enabled Strict Mode to prevent future direct pushes
+
+**Lesson**: With Strict Mode active, this won't happen again. All releases must go through develop → main PR flow.
 
 ---
 
@@ -213,6 +320,9 @@ A: To promote best practices while respecting contributor flexibility and judgme
 |------|------|--------|
 | 2025-10-17 | Initial policy drafted (Strict Mode)             | git-manager  |
 | 2025-10-17 | Switched to Advisory Mode (warnings only)        | git-manager  |
+| 2025-10-29 | **Enabled GitHub Branch Protection (Strict Mode)** | Alfred       |
+| 2025-10-29 | Added develop-main sync guidelines and real-world case study | Alfred       |
+| 2025-10-29 | Enforced `enforce_admins`, `required_conversation_resolution` | Alfred       |
 
 ---
 

moai_adk/templates/CLAUDE.md

@@ -59,6 +59,64 @@ You are the SuperAgent **🎩 Alfred** of **🗿 MoAI-ADK**. Follow these core p
 
 ---
 
+## 📊 보고서 출력 스타일 (Reporting Style)
+
+**CRITICAL RULE**: Alfred와 모든 Sub-agent는 보고서/완료 안내를 **직접 마크다운 형식**으로 출력해야 합니다.
+
+### ✅ 올바른 패턴: 직접 마크다운 출력
+
+**다음의 경우 직접 마크다운으로 출력:**
+- 작업 완료 보고서 (구현, 테스트, 검증 완료)
+- 세션 최종 정리 (command 완료, PR merge)
+- 진행 상황 요약 (단계별 현황)
+- 다음 단계 안내 (권장 사항)
+- 분석/검증 결과 보고
+
+**출력 예시:**
+```markdown
+## 🎊 작업 완료
+
+### 구현 결과
+- ✅ 기능 구현 완료
+- ✅ 테스트 통과
+
+### 품질 지표
+| 항목 | 결과 |
+|------|------|
+| Coverage | 95% |
+
+### 다음 단계
+1. 권장 작업
+```
+
+### ❌ 금지된 패턴: Bash/Python Wrapping
+
+**다음 방식으로 보고서를 wrapping하지 마세요:**
+```bash
+# ❌ 잘못된 예시
+cat << 'EOF'
+## 보고서
+EOF
+
+python -c "print('보고서')"
+echo "보고서"
+```
+
+### 📋 작성 가이드라인
+
+1. **마크다운 포맷**: 헤딩, 테이블, 리스트, 이모지 (✅/❌/⚠️/🎊/📊)
+2. **보고서 길이**: 짧으면 한 번에, 길면 섹션 분할
+3. **언어 설정**: 사용자의 `conversation_language` 준수
+4. **Bash 도구 예외**: 실제 시스템 명령 실행 시에만 사용 (파일 조작, Git, 패키지 관리)
+
+**적용 시점:**
+- Command 완료 시 (항상)
+- Sub-agent 작업 완료 시 (대부분)
+- 품질 검증 완료 시
+- Git 작업 완료 시
+
+---
+
 ## 🌍 Alfred's Language Boundary Rule
 
 Alfred operates with a **clear two-layer language architecture** to support global users while keeping the infrastructure in English: