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

moai_adk/templates/.moai/hooks/install.sh

@@ -0,0 +1,79 @@
+#!/bin/bash
+# @CODE:DOC-TAG-004 | Component 1: Pre-commit hook installer
+#
+# This script installs the TAG validation pre-commit hook into .git/hooks/
+#
+# Usage:
+#   ./install.sh              # Install hook
+#   ./install.sh --uninstall  # Remove hook
+
+set -e
+
+# Colors
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+RED='\033[0;31m'
+NC='\033[0m'
+
+# Get repository root
+REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || echo ".")
+HOOK_SOURCE="${REPO_ROOT}/.moai/hooks/pre-commit.sh"
+HOOK_TARGET="${REPO_ROOT}/.git/hooks/pre-commit"
+
+# Function to install hook
+install_hook() {
+    echo "🔧 Installing TAG validation pre-commit hook..."
+
+    # Check if source exists
+    if [ ! -f "$HOOK_SOURCE" ]; then
+        echo -e "${RED}Error: Hook source not found at $HOOK_SOURCE${NC}"
+        exit 1
+    fi
+
+    # Check if target already exists
+    if [ -f "$HOOK_TARGET" ]; then
+        echo -e "${YELLOW}Warning: Pre-commit hook already exists.${NC}"
+        echo "Backing up existing hook to ${HOOK_TARGET}.backup"
+        cp "$HOOK_TARGET" "${HOOK_TARGET}.backup"
+    fi
+
+    # Create .git/hooks directory if it doesn't exist
+    mkdir -p "$(dirname "$HOOK_TARGET")"
+
+    # Copy hook
+    cp "$HOOK_SOURCE" "$HOOK_TARGET"
+    chmod +x "$HOOK_TARGET"
+
+    echo -e "${GREEN}✓ Pre-commit hook installed successfully!${NC}"
+    echo ""
+    echo "The hook will now validate TAG annotations on every commit."
+    echo ""
+    echo "To uninstall: $0 --uninstall"
+}
+
+# Function to uninstall hook
+uninstall_hook() {
+    echo "🔧 Uninstalling TAG validation pre-commit hook..."
+
+    if [ ! -f "$HOOK_TARGET" ]; then
+        echo -e "${YELLOW}No pre-commit hook installed.${NC}"
+        exit 0
+    fi
+
+    # Check if backup exists
+    if [ -f "${HOOK_TARGET}.backup" ]; then
+        echo "Restoring backup..."
+        mv "${HOOK_TARGET}.backup" "$HOOK_TARGET"
+        echo -e "${GREEN}✓ Backup restored.${NC}"
+    else
+        rm "$HOOK_TARGET"
+        echo -e "${GREEN}✓ Pre-commit hook removed.${NC}"
+    fi
+}
+
+# Parse command line arguments
+if [ "$1" = "--uninstall" ]; then
+    uninstall_hook
+else
+    install_hook
+fi

moai_adk/templates/.moai/hooks/pre-commit.sh

@@ -0,0 +1,66 @@
+#!/bin/bash
+# @CODE:DOC-TAG-004 | Component 1: Pre-commit hook for TAG validation
+#
+# This hook validates TAG annotations in staged files before commit.
+# It checks:
+# - TAG format (@DOC:DOMAIN-TYPE-NNN)
+# - Duplicate TAG detection
+# - Orphan TAG detection (warnings only)
+#
+# Exit codes:
+#   0 - Validation passed
+#   1 - Validation failed (duplicates or format errors)
+
+set -e  # Exit on error
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+# Get repository root
+REPO_ROOT=$(git rev-parse --show-toplevel)
+
+# Check if Python module is available
+if ! python3 -c "import moai_adk.core.tags.pre_commit_validator" 2>/dev/null; then
+    echo -e "${YELLOW}Warning: moai_adk TAG validator not found.${NC}"
+    echo "Skipping TAG validation. Install moai_adk to enable validation."
+    exit 0
+fi
+
+# Get staged files
+STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM)
+
+if [ -z "$STAGED_FILES" ]; then
+    echo -e "${GREEN}No staged files to validate.${NC}"
+    exit 0
+fi
+
+echo "🔍 Validating TAG annotations in staged files..."
+
+# Run TAG validation
+# Pass staged files as arguments to validator
+python3 -m moai_adk.core.tags.pre_commit_validator \
+    --files $STAGED_FILES
+
+VALIDATION_RESULT=$?
+
+# Check result
+if [ $VALIDATION_RESULT -eq 0 ]; then
+    echo -e "${GREEN}✓ TAG validation passed.${NC}"
+    exit 0
+else
+    echo -e "${RED}✗ TAG validation failed.${NC}"
+    echo ""
+    echo "Commit blocked due to TAG validation errors."
+    echo ""
+    echo "To fix:"
+    echo "  1. Fix duplicate TAGs or format errors shown above"
+    echo "  2. Stage your changes with 'git add'"
+    echo "  3. Try committing again"
+    echo ""
+    echo "To skip this validation (not recommended):"
+    echo "  git commit --no-verify"
+    exit 1
+fi

moai_adk/templates/.moai/memory/GITFLOW-PROTECTION-POLICY.md

@@ -0,0 +1,220 @@
+# GitFlow Advisory Policy
+
+**Document ID**: @DOC:GITFLOW-POLICY-001  
+**Published**: 2025-10-17  
+**Status**: Advisory (recommended, not enforced)  
+**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.
+
+## Key Recommendations
+
+### 1. Main Branch Access (Recommended)
+
+| 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 ⚠️ |
+
+### 2. Git Workflow (Recommended)
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                RECOMMENDED GITFLOW                      │
+└─────────────────────────────────────────────────────────┘
+
+        develop (recommended base branch)
+          ↑     ↓
+    ┌─────────────────┐
+    │                 │
+    │   developer work │
+    │                 │
+    ↓                 ↑
+feature/SPEC-{ID}   [PR: feature -> develop]
+                     [code review + approval]
+                     [Merge to develop]
+
+    develop (stable)
+         ↓
+         │   (release manager prepares)
+         ↓
+    [PR: develop -> main]
+    [CI/CD validation]
+    [tag creation]
+         ↓
+       main (release)
+```
+
+**Flexibility**: Direct pushes to `main` are still possible, but the workflow above is preferred.
+
+## 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 (Legacy, Currently Disabled)
+
+- ❌ Block direct pushes to `main`
+- ❌ Block force pushes
+- ❌ Block merges into `main` from any branch other than `develop`
+
+### Advisory Mode (Active, v0.3.5+)
+
+- ⚠️ Warn but allow direct pushes to `main`
+- ⚠️ Warn but allow force pushes
+- ⚠️ Recommend best practices while preserving flexibility
+- ✅ Respect user judgment
+
+---
+
+## 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: To promote best practices while respecting contributor flexibility and judgment.
+
+---
+
+## 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  |
+
+---
+
+**This policy is advisory—adapt it to fit your project needs.**  
+**Reach out to the team lead or release engineer for questions or suggestions.**

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

@@ -1,40 +1,36 @@
-# GitFlow Protection Policy
+# GitFlow Advisory Policy
 
-**Document ID**: @DOC:GITFLOW-POLICY-ALIAS
-**Published**: 2025-10-17
-**Updated**: 2025-10-29
-**Status**: **Enforced via GitHub Branch Protection** (v0.8.3+)
+**Document ID**: @DOC:GITFLOW-POLICY-001  
+**Published**: 2025-10-17  
+**Status**: Advisory (recommended, not enforced)  
 **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.
+MoAI-ADK **recommends** a GitFlow-inspired workflow. This policy shares best practices while letting teams adapt them as needed.
 
-**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 Recommendations
 
-## Key Requirements (Enforced)
+### 1. Main Branch Access (Recommended)
 
-### 1. Main Branch Access (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 ⚠️ |
 
-| 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)
+### 2. Git Workflow (Recommended)
 
 ```
 ┌─────────────────────────────────────────────────────────┐
-│                ENFORCED GITFLOW                         │
-│         (GitHub Branch Protection Active)               │
+│                RECOMMENDED GITFLOW                      │
 └─────────────────────────────────────────────────────────┘
 
-        develop (required base branch)
+        develop (recommended base branch)
           ↑     ↓
     ┌─────────────────┐
     │                 │
@@ -50,15 +46,13 @@ 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 (protected release)
+       main (release)
 ```
 
-**Enforcement**: Direct pushes to `main` are **blocked** via GitHub Branch Protection. All changes must go through Pull Requests.
+**Flexibility**: Direct pushes to `main` are still possible, but the workflow above is preferred.
 
 ## Technical Implementation
 
@@ -162,29 +156,18 @@ 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
+### Strict Mode (Legacy, Currently Disabled)
 
-**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
+- ❌ Block direct pushes to `main`
+- ❌ Block force pushes
+- ❌ Block merges into `main` from any branch other than `develop`
 
-### Advisory Mode (Legacy, v0.3.5 - v0.8.2)
+### Advisory Mode (Active, v0.3.5+)
 
-- ⚠️ 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
+- ⚠️ Warn but allow direct pushes to `main`
+- ⚠️ Warn but allow force pushes
+- ⚠️ Recommend best practices while preserving flexibility
+- ✅ Respect user judgment
 
 ---
 
@@ -219,98 +202,8 @@ 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.
+**Q: Why switch to Advisory Mode?**  
+A: To promote best practices while respecting contributor flexibility and judgment.
 
 ---
 
@@ -320,9 +213,6 @@ git push origin develop
 |------|------|--------|
 | 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       |
 
 ---