moai-adk 0.8.2__py3-none-any.whl → 0.9.0__py3-none-any.whl

moai_adk/templates/.claude/hooks/alfred/core/version_cache.py

@@ -149,7 +149,7 @@ class VersionCache:
 
             return True
 
-        except (OSError, TypeError) as e:
+        except (OSError, TypeError):
             # Graceful degradation on write errors
             return False
 

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
 
@@ -458,7 +519,7 @@ def is_network_available(timeout_seconds: float = 0.1) -> bool:
         return False
 
 
-# @CODE:MAJOR-UPDATE-WARN-001
+# @CODE:VERSION-DETECT-MAJOR-001
 def is_major_version_change(current: str, latest: str) -> bool:
     """Detect if version change is a major version bump.
 
@@ -538,7 +599,7 @@ def get_package_version_info(cwd: str = ".") -> dict[str, Any]:
         - 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:MAJOR-UPDATE-WARN-001)
+        - Phase 3: Add release_notes_url and is_major_update fields (@CODE:VERSION-INTEGRATE-FIELDS-001)
     """
     import importlib.util
     import urllib.error
@@ -556,52 +617,68 @@ def get_package_version_info(cwd: str = ".") -> dict[str, Any]:
         else:
             # Skip caching if module can't be loaded
             VersionCache = None
-    except (ImportError, OSError) as e:
+    except (ImportError, OSError):
         # 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. Try to load from cache (fast path)
+    # 2. Get current installed version first (needed for cache validation)
+    current_version = "unknown"
+    try:
+        current_version = version("moai-adk")
+    except PackageNotFoundError:
+        current_version = "dev"
+        # Dev mode - skip cache and return immediately
+        return {
+            "current": "dev",
+            "latest": "unknown",
+            "update_available": False,
+            "upgrade_command": ""
+        }
+
+    # 3. Try to load from cache (fast path with version validation)
     if version_cache and version_cache.is_valid():
         cached_info = version_cache.load()
         if cached_info:
-            # Ensure new fields exist for backward compatibility
-            if "release_notes_url" not in cached_info:
-                # Add missing fields to old cached data
-                cached_info.setdefault("release_notes_url", None)
-                cached_info.setdefault("is_major_update", False)
-            return cached_info
-
-    # 3. Cache miss - need to query PyPI
+            # Only use cache if the cached version matches current installed version
+            # This prevents stale cache when package is upgraded locally
+            if cached_info.get("current") == current_version:
+                # Ensure new fields exist for backward compatibility
+                if "release_notes_url" not in cached_info:
+                    # Add missing fields to old cached data
+                    cached_info.setdefault("release_notes_url", None)
+                    cached_info.setdefault("is_major_update", False)
+                return cached_info
+            # else: cache is stale (version changed), fall through to re-check
+
+    # 4. Cache miss or stale - need to query PyPI
     result = {
-        "current": "unknown",
+        "current": current_version,
         "latest": "unknown",
         "update_available": False,
         "upgrade_command": ""
     }
 
-    # Get current version
-    try:
-        result["current"] = version("moai-adk")
-    except PackageNotFoundError:
-        result["current"] = "dev"
-        return result
-
-    # 4. Check if version check is enabled in config (Phase 4)
+    # 5. Check if version check is enabled in config
     config = get_version_check_config(cwd)
     if not config["enabled"]:
         # Version check disabled - return only current version
         return result
 
-    # 5. Check network before PyPI query
+    # 6. Check network before PyPI query
     if not is_network_available():
         # Offline mode - return current version only
         return result
 
-    # 6. Network available - query PyPI
+    # 7. Network available - query PyPI
     pypi_data = None
     try:
         with timeout_handler(1):
@@ -661,6 +738,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/.claude/hooks/alfred/shared/core/version_cache.py

@@ -37,12 +37,12 @@ class VersionCache:
         '0.8.1'
     """
 
-    def __init__(self, cache_dir: Path, ttl_hours: int = 24):
+    def __init__(self, cache_dir: Path, ttl_hours: int = 4):
         """Initialize cache with TTL in hours
 
         Args:
             cache_dir: Directory where cache file will be stored
-            ttl_hours: Time-to-live in hours (default 24)
+            ttl_hours: Time-to-live in hours (default 4)
         """
         self.cache_dir = Path(cache_dir)
         self.ttl_hours = ttl_hours
@@ -149,7 +149,7 @@ class VersionCache:
 
             return True
 
-        except (OSError, TypeError) as e:
+        except (OSError, TypeError):
             # Graceful degradation on write errors
             return False
 

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

@@ -0,0 +1,330 @@
+# GitFlow Protection Policy
+
+**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 **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.
+
+**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.
+
+## Key Requirements (Enforced)
+
+### 1. Main Branch Access (Enforced)
+
+| 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)
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                ENFORCED GITFLOW                         │
+│         (GitHub Branch Protection Active)               │
+└─────────────────────────────────────────────────────────┘
+
+        develop (required base branch)
+          ↑     ↓
+    ┌─────────────────┐
+    │                 │
+    │   developer work │
+    │                 │
+    ↓                 ↑
+feature/SPEC-{ID}   [PR: feature -> develop]
+                     [code review + approval]
+                     [Merge to develop]
+
+    develop (stable)
+         ↓
+         │   (release manager prepares)
+         ↓
+    [PR: develop -> main]
+    [Code review + approval REQUIRED]
+    [All discussions resolved]
+    [CI/CD validation]
+    [tag creation]
+         ↓
+       main (protected release)
+```
+
+**Enforcement**: Direct pushes to `main` are **blocked** via GitHub Branch Protection. All changes must go through Pull Requests.
+
+## Technical Implementation
+
+### Pre-push Hook (Advisory Mode)
+
+**Location**: `.git/hooks/pre-push`  
+**Purpose**: Warn on `main` branch pushes without blocking them
+
+```bash
+# When attempting to push to main:
+⚠️  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)
+```
+
+### Force 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)
+```
+
+---
+
+## Workflow Examples
+
+### Scenario 1: Standard Feature Development (Recommended)
+
+```bash
+# 1. Sync latest code from develop
+git checkout develop
+git pull origin develop
+
+# 2. Create a feature branch (from develop)
+git checkout -b feature/SPEC-001-new-feature
+
+# 3. Implement the change
+# ... write code and tests ...
+
+# 4. Commit
+git add .
+git commit -m "..."
+
+# 5. Push
+git push origin feature/SPEC-001-new-feature
+
+# 6. Open a PR: feature/SPEC-001-new-feature -> develop
+
+# 7. Merge into develop after review and approval
+```
+
+### Scenario 2: Fast Hotfix (Flexible)
+
+```bash
+# When an urgent fix is required:
+
+# Option 1: Recommended (via develop)
+git checkout develop
+git checkout -b hotfix/critical-bug
+# ... apply fix ...
+git push origin hotfix/critical-bug
+# Open PRs: hotfix -> develop -> main
+
+# Option 2: Direct fix on main (allowed, not recommended)
+git checkout main
+# ... apply fix ...
+git commit -m "Fix critical bug"
+git push origin main  # ⚠️ Advisory warning appears but push continues
+```
+
+### Scenario 3: Release (Standard or Flexible)
+
+```bash
+# Standard approach (recommended):
+git checkout develop
+gh pr create --base main --head develop --title "Release v1.0.0"
+
+# Direct push (allowed):
+git checkout develop
+git push origin main  # ⚠️ Advisory warning appears but push continues
+git tag -a v1.0.0 -m "Release v1.0.0"
+git push origin v1.0.0
+```
+
+---
+
+## Policy Modes
+
+### 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
+
+**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 (Legacy, v0.3.5 - v0.8.2)
+
+- ⚠️ 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
+
+---
+
+## Recommended Checklist
+
+Every contributor should ensure:
+
+- [ ] `.git/hooks/pre-push` exists and is executable (755)
+- [ ] Feature branches fork from `develop`
+- [ ] Pull requests target `develop`
+- [ ] Releases merge `develop` → `main`
+
+**Verification Commands**:
+```bash
+ls -la .git/hooks/pre-push
+git branch -vv
+```
+
+---
+
+## FAQ
+
+**Q: Can we merge into `main` from branches other than `develop`?**  
+A: Yes. You will see an advisory warning, but the merge proceeds. The recommended path remains `develop` → `main`.
+
+**Q: Are force pushes allowed?**  
+A: Yes. You receive a warning, but the push succeeds. Use with caution.
+
+**Q: Can we commit/push directly to `main`?**  
+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: 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.
+
+---
+
+## Policy Change Log
+
+| Date       | Change                                           | Owner        |
+|------|------|--------|
+| 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       |
+
+---
+
+**This policy is advisory—adapt it to fit your project needs.**  
+**Reach out to the team lead or release engineer for questions or suggestions.**