moai-adk 0.3.2__py3-none-any.whl → 0.3.6__py3-none-any.whl

moai_adk/__init__.py

@@ -4,5 +4,5 @@
 SPEC-First TDD Framework with Alfred SuperAgent
 """
 
-__version__ = "0.3.2"
+__version__ = "0.3.6"
 __all__ = ["__version__"]

moai_adk/cli/commands/update.py

@@ -3,6 +3,7 @@ import json
 from pathlib import Path
 
 import click
+from packaging import version
 from rich.console import Console
 
 from moai_adk import __version__
@@ -11,11 +12,11 @@ from moai_adk.core.template.processor import TemplateProcessor
 console = Console()
 
 
-def get_latest_version() -> str:
+def get_latest_version() -> str | None:
     """Get the latest version from PyPI.
 
     Returns:
-        Latest version string, or current version if fetch fails.
+        Latest version string, or None if fetch fails.
     """
     try:
         import urllib.error
@@ -26,8 +27,8 @@ def get_latest_version() -> str:
             data = json.loads(response.read().decode("utf-8"))
             return data["info"]["version"]
     except (urllib.error.URLError, json.JSONDecodeError, KeyError, TimeoutError):
-        # Fallback to current version if PyPI check fails
-        return __version__
+        # Return None if PyPI check fails
+        return None
 
 
 @click.command()
@@ -73,39 +74,57 @@ def update(path: str, force: bool, check: bool) -> None:
         console.print("[cyan]🔍 Checking versions...[/cyan]")
         current_version = __version__
         latest_version = get_latest_version()
-        console.print(f"   Current version: {current_version}")
-        console.print(f"   Latest version:  {latest_version}")
+
+        # Handle PyPI fetch failure
+        if latest_version is None:
+            console.print(f"   Current version: {current_version}")
+            console.print("   Latest version:  [yellow]Unable to fetch from PyPI[/yellow]")
+            if not force:
+                console.print("[yellow]⚠ Cannot check for updates. Use --force to update anyway.[/yellow]")
+                return
+        else:
+            console.print(f"   Current version: {current_version}")
+            console.print(f"   Latest version:  {latest_version}")
 
         if check:
             # Exit early when --check is provided
-            if current_version == latest_version:
-                console.print("[green]✓ Already up to date[/green]")
-            else:
+            if latest_version is None:
+                console.print("[yellow]⚠ Unable to check for updates[/yellow]")
+            elif version.parse(current_version) < version.parse(latest_version):
                 console.print("[yellow]⚠ Update available[/yellow]")
+            elif version.parse(current_version) > version.parse(latest_version):
+                console.print("[green]✓ Development version (newer than PyPI)[/green]")
+            else:
+                console.print("[green]✓ Already up to date[/green]")
             return
 
         # Check if update is needed (version + optimized status) - skip with --force
-        if not force and current_version == latest_version:
-            # Check optimized status in config.json
-            config_path = project_path / ".moai" / "config.json"
-            if config_path.exists():
-                try:
-                    config_data = json.loads(config_path.read_text())
-                    is_optimized = config_data.get("project", {}).get("optimized", False)
-
-                    if is_optimized:
-                        # Already up to date and optimized - exit silently
-                        return
-                    else:
-                        console.print("[yellow]⚠ Optimization needed[/yellow]")
-                        console.print("[dim]Use /alfred:0-project update for template optimization[/dim]")
-                        return
-                except (json.JSONDecodeError, KeyError):
-                    # If config.json is invalid, proceed with update
-                    pass
-            else:
-                console.print("[green]✓ Already up to date[/green]")
-                return
+        if not force and latest_version is not None:
+            current_ver = version.parse(current_version)
+            latest_ver = version.parse(latest_version)
+
+            # Don't update if current version is newer or equal
+            if current_ver >= latest_ver:
+                # Check optimized status in config.json
+                config_path = project_path / ".moai" / "config.json"
+                if config_path.exists():
+                    try:
+                        config_data = json.loads(config_path.read_text())
+                        is_optimized = config_data.get("project", {}).get("optimized", False)
+
+                        if is_optimized:
+                            # Already up to date and optimized - exit silently
+                            return
+                        else:
+                            console.print("[yellow]⚠ Optimization needed[/yellow]")
+                            console.print("[dim]Use /alfred:0-project update for template optimization[/dim]")
+                            return
+                    except (json.JSONDecodeError, KeyError):
+                        # If config.json is invalid, proceed with update
+                        pass
+                else:
+                    console.print("[green]✓ Already up to date[/green]")
+                    return
 
         # Phase 2: create a backup unless --force
         if not force:

moai_adk/core/project/initializer.py

@@ -103,20 +103,31 @@ class ProjectInitializer:
             # Phase 2: Directory (create directories)
             self.executor.execute_directory_phase(self.path, progress_callback)
 
-            # Phase 3: Resource (copy templates)
+            # Prepare config for template variable substitution (Phase 3)
+            config = {
+                "name": self.path.name,
+                "mode": mode,
+                "locale": locale,
+                "language": detected_language,
+                "description": "",
+                "version": "0.1.0",
+                "author": "@user",
+            }
+
+            # Phase 3: Resource (copy templates with variable substitution)
             resource_files = self.executor.execute_resource_phase(
-                self.path, progress_callback
+                self.path, config, progress_callback
             )
 
-            # Phase 4: Configuration (generate config)
-            config = {
+            # Phase 4: Configuration (generate config.json)
+            config_data: dict[str, str | bool] = {
                 "projectName": self.path.name,
                 "mode": mode,
                 "locale": locale,
                 "language": detected_language,
             }
             config_files = self.executor.execute_configuration_phase(
-                self.path, config, progress_callback
+                self.path, config_data, progress_callback
             )
 
             # Phase 5: Validation (verify and finalize)

moai_adk/core/project/phase_executor.py

@@ -13,6 +13,7 @@ import json
 import shutil
 import subprocess
 from collections.abc import Callable
+from datetime import datetime
 from pathlib import Path
 
 from rich.console import Console
@@ -115,12 +116,14 @@ class PhaseExecutor:
     def execute_resource_phase(
         self,
         project_path: Path,
+        config: dict[str, str] | None = None,
         progress_callback: ProgressCallback | None = None,
     ) -> list[str]:
-        """Phase 3: install resources.
+        """Phase 3: install resources with variable substitution.
 
         Args:
             project_path: Project path.
+            config: Configuration dictionary for template variable substitution.
             progress_callback: Optional progress callback.
 
         Returns:
@@ -135,6 +138,20 @@ class PhaseExecutor:
         from moai_adk.core.template import TemplateProcessor
 
         processor = TemplateProcessor(project_path)
+
+        # Set template variable context (if provided)
+        if config:
+            context = {
+                "MOAI_VERSION": __version__,
+                "CREATION_TIMESTAMP": datetime.now().strftime("%Y-%m-%d %H:%M:%S"),
+                "PROJECT_NAME": config.get("name", "unknown"),
+                "PROJECT_DESCRIPTION": config.get("description", ""),
+                "PROJECT_MODE": config.get("mode", "personal"),
+                "PROJECT_VERSION": config.get("version", "0.1.0"),
+                "AUTHOR": config.get("author", "@user"),
+            }
+            processor.set_context(context)
+
         processor.copy_templates(backup=False, silent=True)  # Avoid progress bar conflicts
 
         # Return a simplified list of generated assets
@@ -148,7 +165,7 @@ class PhaseExecutor:
     def execute_configuration_phase(
         self,
         project_path: Path,
-        config: dict[str, str],
+        config: dict[str, str | bool],
         progress_callback: ProgressCallback | None = None,
     ) -> list[str]:
         """Phase 4: generate configuration.
@@ -185,6 +202,10 @@ class PhaseExecutor:
     ) -> None:
         """Phase 5: validation and wrap-up.
 
+        @CODE:INIT-004:PHASE5 | Phase 5 verification logic
+        @REQ:VALIDATION-001 | SPEC-INIT-004: Verify required files after initialization completion
+        @CODE:INIT-004:PHASE5-INTEGRATION | Integration of validation in Phase 5
+
         Args:
             project_path: Project path.
             mode: Project mode (personal/team).
@@ -195,7 +216,10 @@ class PhaseExecutor:
             "Phase 5: Validation and finalization...", progress_callback
         )
 
-        # Validate installation results
+        # @CODE:INIT-004:VERIFY-001 | Validate installation results
+        # @CODE:INIT-004:VALIDATION-CHECK | Comprehensive installation validation
+        # Verifies all required files including 4 Alfred command files:
+        # - 0-project.md, 1-spec.md, 2-build.md, 3-sync.md
         self.validator.validate_installation(project_path)
 
         # Initialize Git for team mode

moai_adk/core/project/validator.py

@@ -1,7 +1,20 @@
-# @CODE:CORE-PROJECT-003 | SPEC: SPEC-CORE-PROJECT-001.md
+# @CODE:CORE-PROJECT-003 | SPEC: SPEC-CORE-PROJECT-001.md, SPEC-INIT-004.md
+# @CODE:INIT-004:VALIDATION | Chain: SPEC-INIT-004 -> CODE-INIT-004 -> TEST-INIT-004
+# @REQ:VALIDATION-001 | SPEC-INIT-004: Initial verification after installation completion
+# @SPEC:VERIFICATION-001 | SPEC-INIT-004: Verification logic implementation
 """Project initialization validation module.
 
 Validates system requirements and installation results.
+
+SPEC-INIT-004 Enhancement:
+- Alfred command files validation (Phase 5)
+- Explicit missing files reporting
+- Required files verification checklist
+
+TAG Chain:
+  SPEC-INIT-004 (spec.md)
+    └─> @CODE:INIT-004:VALIDATION (this file)
+        └─> @TEST:INIT-004:VALIDATION (test_validator.py)
 """
 
 import shutil
@@ -32,6 +45,14 @@ class ProjectValidator:
         "CLAUDE.md",
     ]
 
+    # Required Alfred command files (SPEC-INIT-004)
+    REQUIRED_ALFRED_COMMANDS = [
+        "0-project.md",
+        "1-spec.md",
+        "2-build.md",
+        "3-sync.md",
+    ]
+
     def validate_system_requirements(self) -> None:
         """Verify system requirements.
 
@@ -76,6 +97,10 @@ class ProjectValidator:
     def validate_installation(self, project_path: Path) -> None:
         """Validate installation results.
 
+        @CODE:INIT-004:VERIFY-001 | Verification of all required files upon successful completion
+        @SPEC:VERIFICATION-001 | SPEC-INIT-004: Verification checklist implementation
+        @REQ:VALIDATION-001 | UR-003: All required files verified after init completes
+
         Args:
             project_path: Project path.
 
@@ -83,17 +108,37 @@ class ProjectValidator:
             ValidationError: Raised when installation was incomplete.
         """
         # Verify required directories
+        # @CODE:INIT-004:VALIDATION-001 | Core project structure validation
         for directory in self.REQUIRED_DIRECTORIES:
             dir_path = project_path / directory
             if not dir_path.exists():
                 raise ValidationError(f"Required directory not found: {directory}")
 
         # Verify required files
+        # @CODE:INIT-004:VALIDATION-002 | Required configuration files validation
         for file in self.REQUIRED_FILES:
             file_path = project_path / file
             if not file_path.exists():
                 raise ValidationError(f"Required file not found: {file}")
 
+        # @CODE:INIT-004:VERIFY-002 | Verify required Alfred command files (SPEC-INIT-004)
+        # @REQ:COMMAND-GENERATION-001 | All 4 Alfred command files must be created
+        # @CODE:INIT-004:ALFRED-VALIDATION | Alfred command file integrity check
+        alfred_dir = project_path / ".claude" / "commands" / "alfred"
+        missing_commands = []
+        for cmd in self.REQUIRED_ALFRED_COMMANDS:
+            cmd_path = alfred_dir / cmd
+            if not cmd_path.exists():
+                missing_commands.append(cmd)
+
+        if missing_commands:
+            missing_list = ", ".join(missing_commands)
+            # @SPEC:ERROR-HANDLING-001 | Clear error messages upon missing files
+            # @CODE:INIT-004:ERROR-MESSAGE | Clear reporting of missing Alfred command files
+            raise ValidationError(
+                f"Required Alfred command files not found: {missing_list}"
+            )
+
     def _is_inside_moai_package(self, project_path: Path) -> bool:
         """Determine whether the path is inside the MoAI-ADK package.
 

moai_adk/core/template/processor.py

@@ -3,6 +3,7 @@
 
 from __future__ import annotations
 
+import re
 import shutil
 from pathlib import Path
 
@@ -38,6 +39,7 @@ class TemplateProcessor:
         self.template_root = self._get_template_root()
         self.backup = TemplateBackup(self.target_path)
         self.merger = TemplateMerger(self.target_path)
+        self.context: dict[str, str] = {}  # Template variable substitution context
 
     def _get_template_root(self) -> Path:
         """Return the template root path."""
@@ -46,6 +48,116 @@ class TemplateProcessor:
         package_root = current_file.parent.parent.parent
         return package_root / "templates"
 
+    def set_context(self, context: dict[str, str]) -> None:
+        """Set variable substitution context.
+
+        Args:
+            context: Dictionary of template variables.
+        """
+        self.context = context
+
+    def _substitute_variables(self, content: str) -> tuple[str, list[str]]:
+        """Substitute template variables in content.
+
+        Returns:
+            Tuple of (substituted_content, warnings_list)
+        """
+        warnings = []
+
+        # Perform variable substitution
+        for key, value in self.context.items():
+            placeholder = f"{{{{{key}}}}}"  # {{KEY}}
+            if placeholder in content:
+                safe_value = self._sanitize_value(value)
+                content = content.replace(placeholder, safe_value)
+
+        # Detect unsubstituted variables
+        remaining = re.findall(r'\{\{([A-Z_]+)\}\}', content)
+        if remaining:
+            unique_remaining = sorted(set(remaining))
+            warnings.append(f"Unsubstituted variables: {', '.join(unique_remaining)}")
+
+        return content, warnings
+
+    def _sanitize_value(self, value: str) -> str:
+        """Sanitize value to prevent recursive substitution and control characters.
+
+        Args:
+            value: Value to sanitize.
+
+        Returns:
+            Sanitized value.
+        """
+        # Remove control characters (keep printable and whitespace)
+        value = ''.join(c for c in value if c.isprintable() or c in '\n\r\t')
+        # Prevent recursive substitution by removing placeholder patterns
+        value = value.replace('{{', '').replace('}}', '')
+        return value
+
+    def _is_text_file(self, file_path: Path) -> bool:
+        """Check if file is text-based (not binary).
+
+        Args:
+            file_path: File path to check.
+
+        Returns:
+            True if file is text-based.
+        """
+        text_extensions = {
+            '.md', '.json', '.txt', '.py', '.ts', '.js',
+            '.yaml', '.yml', '.toml', '.xml', '.sh', '.bash'
+        }
+        return file_path.suffix.lower() in text_extensions
+
+    def _copy_file_with_substitution(self, src: Path, dst: Path) -> list[str]:
+        """Copy file with variable substitution for text files.
+
+        Args:
+            src: Source file path.
+            dst: Destination file path.
+
+        Returns:
+            List of warnings.
+        """
+        warnings = []
+
+        # Text files: read, substitute, write
+        if self._is_text_file(src) and self.context:
+            try:
+                content = src.read_text(encoding='utf-8')
+                content, file_warnings = self._substitute_variables(content)
+                dst.write_text(content, encoding='utf-8')
+                warnings.extend(file_warnings)
+            except UnicodeDecodeError:
+                # Binary file fallback
+                shutil.copy2(src, dst)
+        else:
+            # Binary file or no context: simple copy
+            shutil.copy2(src, dst)
+
+        return warnings
+
+    def _copy_dir_with_substitution(self, src: Path, dst: Path) -> None:
+        """Recursively copy directory with variable substitution for text files.
+
+        Args:
+            src: Source directory path.
+            dst: Destination directory path.
+        """
+        dst.mkdir(parents=True, exist_ok=True)
+
+        for item in src.rglob("*"):
+            rel_path = item.relative_to(src)
+            dst_item = dst / rel_path
+
+            if item.is_file():
+                # Create parent directory if needed
+                dst_item.parent.mkdir(parents=True, exist_ok=True)
+                # Copy with variable substitution
+                self._copy_file_with_substitution(item, dst_item)
+            elif item.is_dir():
+                dst_item.mkdir(parents=True, exist_ok=True)
+
     def copy_templates(self, backup: bool = True, silent: bool = False) -> None:
         """Copy template files into the project.
 
@@ -115,11 +227,16 @@ class TemplateProcessor:
                 dst_item.mkdir(parents=True, exist_ok=True)
 
     def _copy_claude(self, silent: bool = False) -> None:
-        """.claude/ directory copy (selective with alfred folder overwrite).
+        """.claude/ directory copy with variable substitution (selective with alfred folder overwrite).
+
+        @CODE:INIT-004:ALFRED-001 | Copy all 4 Alfred command files from templates
+        @REQ:COMMAND-GENERATION-001 | SPEC-INIT-004: Automatic generation of Alfred command files
+        @SPEC:TEMPLATE-PROCESSING-001 | Template processor integration for Alfred command files
 
         Strategy:
         - Alfred folders (commands/agents/hooks/output-styles/alfred) → copy wholesale (delete & overwrite)
           * Creates individual backup before deletion for safety
+          * Commands: 0-project.md, 1-spec.md, 2-build.md, 3-sync.md
         - Other files/folders → copy individually (preserve existing)
         """
         src = self.template_root / ".claude"
@@ -133,10 +250,12 @@ class TemplateProcessor:
         # Create .claude directory if not exists
         dst.mkdir(parents=True, exist_ok=True)
 
+        # @CODE:INIT-004:ALFRED-002 | Alfred command files must always be overwritten
+        # @CODE:INIT-004:ALFRED-COPY | Copy all 4 Alfred command files from templates
         # Alfred folders to copy wholesale (overwrite)
         alfred_folders = [
             "hooks/alfred",
-            "commands/alfred",
+            "commands/alfred",  # Contains 0-project.md, 1-spec.md, 2-build.md, 3-sync.md
             "output-styles/alfred",
             "agents/alfred",
         ]
@@ -158,7 +277,8 @@ class TemplateProcessor:
                 if not silent:
                     console.print(f"   ✅ .claude/{folder}/ overwritten")
 
-        # 2. Copy other files/folders individually (preserve existing)
+        # 2. Copy other files/folders individually (preserve existing, with substitution)
+        all_warnings = []
         for item in src.iterdir():
             rel_path = item.relative_to(src)
             dst_item = dst / rel_path
@@ -170,14 +290,23 @@ class TemplateProcessor:
             if item.is_file():
                 # Copy file, skip if exists (preserve user modifications)
                 if not dst_item.exists():
-                    shutil.copy2(item, dst_item)
+                    # Copy with variable substitution for text files
+                    warnings = self._copy_file_with_substitution(item, dst_item)
+                    all_warnings.extend(warnings)
             elif item.is_dir():
                 # Copy directory recursively (preserve existing files)
                 if not dst_item.exists():
-                    shutil.copytree(item, dst_item)
+                    # Recursively copy directory with substitution
+                    self._copy_dir_with_substitution(item, dst_item)
+
+        # Print warnings if any
+        if all_warnings and not silent:
+            console.print("[yellow]⚠️ Template warnings:[/yellow]")
+            for warning in set(all_warnings):  # Deduplicate
+                console.print(f"   {warning}")
 
         if not silent:
-            console.print("   ✅ .claude/ copy complete (alfred folders overwritten, others preserved)")
+            console.print("   ✅ .claude/ copy complete (variables substituted)")
 
     def _backup_alfred_folder(self, folder_path: Path, folder_name: str) -> None:
         """Backup an Alfred folder before overwriting (safety measure).
@@ -205,7 +334,7 @@ class TemplateProcessor:
         shutil.copytree(folder_path, backup_folder)
 
     def _copy_moai(self, silent: bool = False) -> None:
-        """.moai/ directory copy (excludes protected paths)."""
+        """.moai/ directory copy with variable substitution (excludes protected paths)."""
         src = self.template_root / ".moai"
         dst = self.target_path / ".moai"
 
@@ -220,6 +349,8 @@ class TemplateProcessor:
             "reports",
         ]
 
+        all_warnings = []
+
         # Copy while skipping protected paths
         for item in src.rglob("*"):
             rel_path = item.relative_to(src)
@@ -235,15 +366,23 @@ class TemplateProcessor:
                 if dst_item.exists():
                     continue
                 dst_item.parent.mkdir(parents=True, exist_ok=True)
-                shutil.copy2(item, dst_item)
+                # Copy with variable substitution
+                warnings = self._copy_file_with_substitution(item, dst_item)
+                all_warnings.extend(warnings)
             elif item.is_dir():
                 dst_item.mkdir(parents=True, exist_ok=True)
 
+        # Print warnings if any
+        if all_warnings and not silent:
+            console.print("[yellow]⚠️ Template warnings:[/yellow]")
+            for warning in set(all_warnings):  # Deduplicate
+                console.print(f"   {warning}")
+
         if not silent:
-            console.print("   ✅ .moai/ copy complete (user content preserved)")
+            console.print("   ✅ .moai/ copy complete (variables substituted)")
 
     def _copy_claude_md(self, silent: bool = False) -> None:
-        """Copy CLAUDE.md with smart merging."""
+        """Copy CLAUDE.md with smart merging and variable substitution."""
         src = self.template_root / "CLAUDE.md"
         dst = self.target_path / "CLAUDE.md"
 
@@ -258,7 +397,8 @@ class TemplateProcessor:
             if not silent:
                 console.print("   🔄 CLAUDE.md merged (project information preserved)")
         else:
-            shutil.copy2(src, dst)
+            # Copy with variable substitution
+            self._copy_file_with_substitution(src, dst)
             if not silent:
                 console.print("   ✅ CLAUDE.md copy complete")
 

moai_adk/templates/.moai/hooks/pre-push.sample

@@ -0,0 +1,88 @@
+#!/bin/bash
+
+# MoAI-ADK GitFlow Main Branch Advisory Hook
+# Purpose: Advisory warnings for main branch operations (not blocking)
+# Enforces: Best practices with flexibility
+#
+# This hook runs before any git push operation and provides advisories:
+# 1. Warns about direct push to main branch (but allows it)
+# 2. Warns about force-push to main branch (but allows it)
+# 3. Recommends GitFlow best practices
+#
+# Exit codes:
+# 0 - Push allowed (always)
+
+set -e
+
+# Colors for output
+RED='\033[0;31m'
+YELLOW='\033[1;33m'
+GREEN='\033[0;32m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# 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)
+
+        # 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 (flexibility mode 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 (flexibility mode 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 (flexibility mode enabled)${NC}"
+                    echo ""
+                fi
+            fi
+        fi
+    fi
+done
+
+# All checks passed (or advisory warnings shown)
+exit 0