moai-adk 0.25.4__py3-none-any.whl → 0.32.8__py3-none-any.whl

moai_adk/core/spec/quality_validator.py

@@ -10,6 +10,9 @@ from moai_adk.core.spec.confidence_scoring import ConfidenceScoringSystem
 # Configure logging
 logger = logging.getLogger(__name__)
 
+# Traceability tag patterns
+TRACEABILITY_TAGS = ["@SPEC:", "@REQ:", "@TEST:", "@IMPL:", "@DOC:"]
+
 
 class QualityValidator:
     """
@@ -92,7 +95,7 @@ class QualityValidator:
         logger.info("Starting SPEC quality validation")
 
         # Initialize validation results
-        validation_result = {
+        validation_result: Dict[str, Any] = {
             "validation_time": 0.0,
             "overall_score": 0.0,
             "quality_grade": "F",
@@ -113,9 +116,7 @@ class QualityValidator:
             validation_result["details"]["content_completeness"] = completeness_result
 
             # Validate technical accuracy
-            technical_result = self._validate_technical_accuracy(
-                spec_content, code_analysis
-            )
+            technical_result = self._validate_technical_accuracy(spec_content, code_analysis)
             validation_result["details"]["technical_accuracy"] = technical_result
 
             # Validate clarity and readability
@@ -131,9 +132,7 @@ class QualityValidator:
             validation_result["overall_score"] = overall_score
 
             # Determine quality grade
-            validation_result["quality_grade"] = self._determine_quality_grade(
-                overall_score
-            )
+            validation_result["quality_grade"] = self._determine_quality_grade(overall_score)
 
             # Check if SPEC meets minimum quality standards
             meets_standards = self._check_quality_standards(validation_result)
@@ -144,12 +143,8 @@ class QualityValidator:
             validation_result["recommendations"] = recommendations
 
             # Compile check results
-            validation_result["passed_checks"] = self._compile_passed_checks(
-                validation_result["details"]
-            )
-            validation_result["failed_checks"] = self._compile_failed_checks(
-                validation_result["details"]
-            )
+            validation_result["passed_checks"] = self._compile_passed_checks(validation_result["details"])
+            validation_result["failed_checks"] = self._compile_failed_checks(validation_result["details"])
 
         except Exception as e:
             logger.error(f"Error during SPEC validation: {str(e)}")
@@ -158,9 +153,7 @@ class QualityValidator:
         # Set validation time
         validation_result["validation_time"] = time.time() - start_time
 
-        logger.info(
-            f"SPEC quality validation completed in {validation_result['validation_time']:.2f}s"
-        )
+        logger.info(f"SPEC quality validation completed in {validation_result['validation_time']:.2f}s")
 
         return validation_result
 
@@ -184,6 +177,10 @@ class QualityValidator:
         overall_compliance = sum(section_scores.values()) / len(required_sections)
 
         # Check for META information
+        has_meta = "---" in spec_md and "title:" in spec_md
+
+        # Check for tags
+        has_tags = self._check_traceability_tags(spec_md)
 
         # Check for proper structure
         has_proper_headings = self._check_heading_structure(spec_md)
@@ -196,14 +193,10 @@ class QualityValidator:
             "has_tags": has_tags,
             "has_proper_structure": has_proper_headings,
             "total_sections": len(required_sections),
-            "present_sections": sum(
-                1 for score in section_scores.values() if score > 0
-            ),
+            "present_sections": sum(1 for score in section_scores.values() if score > 0),
         }
 
-    def _validate_content_completeness(
-        self, spec_content: Dict[str, str]
-    ) -> Dict[str, Any]:
+    def _validate_content_completeness(self, spec_content: Dict[str, str]) -> Dict[str, Any]:
         """Validate content completeness across all SPEC files."""
         logger.info("Validating content completeness")
 
@@ -230,9 +223,7 @@ class QualityValidator:
         results["acceptance_completeness"] = acceptance_completeness
 
         # Calculate overall completeness
-        overall_completeness = (
-            spec_completeness + plan_completeness + acceptance_completeness
-        ) / 3
+        overall_completeness = (spec_completeness + plan_completeness + acceptance_completeness) / 3
         results["overall_completeness"] = round(overall_completeness, 2)
 
         return results
@@ -301,13 +292,7 @@ class QualityValidator:
             "ambiguity_score": ambiguity_score,
             "consistency_score": consistency_score,
             "overall_clarity": round(
-                (
-                    language_quality
-                    + clarity_requirements
-                    + (1.0 - ambiguity_score)
-                    + consistency_score
-                )
-                / 4,
+                (language_quality + clarity_requirements + (1.0 - ambiguity_score) + consistency_score) / 4,
                 2,
             ),
         }
@@ -331,12 +316,9 @@ class QualityValidator:
         weights = self.quality_weights
 
         overall_score = (
-            details["ears_compliance"]["overall_compliance"]
-            * weights["ears_compliance"]
-            + details["content_completeness"]["overall_completeness"]
-            * weights["content_completeness"]
-            + details["technical_accuracy"]["overall_accuracy"]
-            * weights["technical_accuracy"]
+            details["ears_compliance"]["overall_compliance"] * weights["ears_compliance"]
+            + details["content_completeness"]["overall_completeness"] * weights["content_completeness"]
+            + details["technical_accuracy"]["overall_accuracy"] * weights["technical_accuracy"]
             + details["clarity_score"]["overall_clarity"] * weights["clarity_score"]
             + details["traceability"]["overall_traceability"] * weights["traceability"]
         )
@@ -359,9 +341,7 @@ class QualityValidator:
     def _check_quality_standards(self, validation_result: Dict[str, Any]) -> bool:
         """Check if SPEC meets minimum quality standards."""
         overall_score = validation_result["overall_score"]
-        ears_compliance = validation_result["details"]["ears_compliance"][
-            "overall_compliance"
-        ]
+        ears_compliance = validation_result["details"]["ears_compliance"]["overall_compliance"]
 
         meets_overall = overall_score >= self.min_confidence_score
         meets_ears = ears_compliance >= self.min_ears_compliance
@@ -376,15 +356,11 @@ class QualityValidator:
         # EARS compliance recommendations
         if details["ears_compliance"]["overall_compliance"] < 1.0:
             missing = details["ears_compliance"]["missing_sections"]
-            recommendations.append(
-                f"Add missing EARS sections: {', '.join(missing[:3])}"
-            )
+            recommendations.append(f"Add missing EARS sections: {', '.join(missing[:3])}")
 
         # Content completeness recommendations
         if details["content_completeness"]["overall_completeness"] < 0.8:
-            recommendations.append(
-                "Expand content sections with more detailed requirements"
-            )
+            recommendations.append("Expand content sections with more detailed requirements")
 
         # Technical accuracy recommendations
         if details["technical_accuracy"]["overall_accuracy"] < 0.8:
@@ -494,9 +470,7 @@ class QualityValidator:
 
         return min(score, 1.0)
 
-    def _assess_acceptance_criteria_completeness(
-        self, acceptance_content: str
-    ) -> float:
+    def _assess_acceptance_criteria_completeness(self, acceptance_content: str) -> float:
         """Assess completeness of acceptance criteria."""
         if not acceptance_content:
             return 0.0
@@ -526,9 +500,7 @@ class QualityValidator:
 
         return len(found_keywords) / len(keywords)
 
-    def _check_code_consistency(
-        self, spec_md: str, code_analysis: Dict[str, Any]
-    ) -> float:
+    def _check_code_consistency(self, spec_md: str, code_analysis: Dict[str, Any]) -> float:
         """Check consistency between SPEC and code analysis."""
         # Extract key elements from code analysis
         classes = code_analysis.get("structure_info", {}).get("classes", [])
@@ -590,9 +562,7 @@ class QualityValidator:
             r"Relevant",
         ]
 
-        found_indicators = sum(
-            1 for indicator in clarity_indicators if re.search(indicator, spec_md)
-        )
+        found_indicators = sum(1 for indicator in clarity_indicators if re.search(indicator, spec_md))
 
         return min(found_indicators / len(clarity_indicators), 1.0)
 
@@ -606,9 +576,7 @@ class QualityValidator:
             r"around",
         ]
 
-        ambiguous_count = sum(
-            1 for indicator in ambiguity_indicators if re.search(indicator, spec_md)
-        )
+        ambiguous_count = sum(1 for indicator in ambiguity_indicators if re.search(indicator, spec_md))
 
         # Normalize by content length
         content_length = len(spec_md.split())
@@ -633,7 +601,7 @@ class QualityValidator:
 
     def _check_traceability_tags(self, spec_md: str) -> bool:
         """Check for traceability tags."""
-        return any(tag in spec_md for tag in traceability_tags)
+        return any(tag in spec_md for tag in TRACEABILITY_TAGS)
 
     def _check_tag_formatting(self, spec_md: str) -> float:
         """Check proper tag formatting."""
@@ -659,9 +627,7 @@ class QualityValidator:
             r"Trace",
         ]
 
-        found_indicators = sum(
-            1 for indicator in traceability_indicators if re.search(indicator, spec_md)
-        )
+        found_indicators = sum(1 for indicator in traceability_indicators if re.search(indicator, spec_md))
 
         return min(found_indicators / len(traceability_indicators), 1.0)
 
@@ -691,14 +657,14 @@ class QualityValidator:
         report = f"""
 # Quality Validation Report
 
-## Overall Quality Score: {validation_result['overall_score']:.2f}/1.0
-## Quality Grade: {validation_result['quality_grade']}
-## Validation Time: {validation_result['validation_time']:.2f}s
+## Overall Quality Score: {validation_result["overall_score"]:.2f}/1.0
+## Quality Grade: {validation_result["quality_grade"]}
+## Validation Time: {validation_result["validation_time"]:.2f}s
 
 ## Summary
-- Passed Checks: {len(validation_result['passed_checks'])}
-- Failed Checks: {len(validation_result['failed_checks'])}
-- Recommendations: {len(validation_result['recommendations'])}
+- Passed Checks: {len(validation_result["passed_checks"])}
+- Failed Checks: {len(validation_result["failed_checks"])}
+- Recommendations: {len(validation_result["recommendations"])}
 
 ## Detailed Metrics
 """

moai_adk/core/spec_status_manager.py

@@ -8,9 +8,9 @@ import logging
 import re
 from datetime import datetime
 from pathlib import Path
-from typing import Dict, Set
+from typing import Any, Dict, List, Set
 
-import yaml
+import yaml  # type: ignore
 
 logger = logging.getLogger(__name__)
 
@@ -43,7 +43,7 @@ class SpecStatusManager:
         Returns:
             Set of SPEC IDs that have draft status
         """
-        draft_specs = set()
+        draft_specs: Set[str] = set()
 
         if not self.specs_dir.exists():
             logger.warning(f"SPEC directory not found: {self.specs_dir}")
@@ -61,9 +61,7 @@ class SpecStatusManager:
                         frontmatter = None
 
                         # Handle JSON-like meta (common in older specs)
-                        meta_match = re.search(
-                            r"<%?\s*---\s*\n(.*?)\n---\s*%?>", content, re.DOTALL
-                        )
+                        meta_match = re.search(r"<%?\s*---\s*\n(.*?)\n---\s*%?>", content, re.DOTALL)
                         if meta_match:
                             try:
                                 meta_text = meta_match.group(1)
@@ -71,9 +69,7 @@ class SpecStatusManager:
                                 meta_text = meta_text.replace('"', "").replace("'", "")
                                 frontmatter = yaml.safe_load("{" + meta_text + "}")
                             except Exception as e:
-                                logger.debug(
-                                    f"JSON meta parsing failed for {spec_dir.name}: {e}"
-                                )
+                                logger.debug(f"JSON meta parsing failed for {spec_dir.name}: {e}")
 
                         # Handle regular YAML frontmatter
                         elif content.startswith("---"):
@@ -83,9 +79,7 @@ class SpecStatusManager:
                                 try:
                                     frontmatter = yaml.safe_load(frontmatter_text)
                                 except yaml.YAMLError as e:
-                                    logger.warning(
-                                        f"YAML parsing error for {spec_dir.name}: {e}"
-                                    )
+                                    logger.warning(f"YAML parsing error for {spec_dir.name}: {e}")
                                     # Try to fix common issues (like @ in author field)
                                     try:
                                         # Replace problematic @author entries
@@ -97,10 +91,8 @@ class SpecStatusManager:
                                                 fixed_text,
                                             )
                                         frontmatter = yaml.safe_load(fixed_text)
-                                    except:
-                                        logger.error(
-                                            f"Could not parse YAML for {spec_dir.name} even after fixes"
-                                        )
+                                    except yaml.YAMLError:
+                                        logger.error(f"Could not parse YAML for {spec_dir.name} even after fixes")
                                         continue
 
                         if frontmatter and frontmatter.get("status") == "draft":
@@ -135,19 +127,11 @@ class SpecStatusManager:
             spec_dir = spec_file.parent
 
             # Check for implementation files
-            src_files = (
-                list(spec_dir.rglob("*.py"))
-                if (spec_dir.parent.parent / "src").exists()
-                else []
-            )
+            src_files = list(spec_dir.rglob("*.py")) if (spec_dir.parent.parent / "src").exists() else []
 
             # Check for test files
             test_dir = spec_dir.parent.parent / "tests"
-            test_files = (
-                list(test_dir.rglob(f"test_*{spec_id.lower()}*.py"))
-                if test_dir.exists()
-                else []
-            )
+            test_files = list(test_dir.rglob(f"test_*{spec_id.lower()}*.py")) if test_dir.exists() else []
 
             # Simple completion criteria
             has_code = len(src_files) > 0
@@ -161,9 +145,7 @@ class SpecStatusManager:
             # Overall completion check
             is_complete = has_code and has_tests and has_acceptance_criteria
 
-            logger.info(
-                f"SPEC {spec_id} implementation status: {'COMPLETE' if is_complete else 'INCOMPLETE'}"
-            )
+            logger.info(f"SPEC {spec_id} implementation status: {'COMPLETE' if is_complete else 'INCOMPLETE'}")
             return is_complete
 
         except Exception as e:
@@ -204,14 +186,10 @@ class SpecStatusManager:
                         try:
                             fixed_text = frontmatter_text
                             if "author: @" in fixed_text:
-                                fixed_text = re.sub(
-                                    r"author:\s*@(\w+)", r'author: "\1"', fixed_text
-                                )
+                                fixed_text = re.sub(r"author:\s*@(\w+)", r'author: "\1"', fixed_text)
                             frontmatter = yaml.safe_load(fixed_text) or {}
-                        except:
-                            logger.error(
-                                f"Could not parse YAML for {spec_id} even after fixes"
-                            )
+                        except yaml.YAMLError:
+                            logger.error(f"Could not parse YAML for {spec_id} even after fixes")
                             return False
 
                     # Update status
@@ -219,14 +197,12 @@ class SpecStatusManager:
 
                     # Bump version if completing
                     if new_status == "completed":
-                        frontmatter["version"] = self._bump_version(
-                            frontmatter.get("version", "0.1.0")
-                        )
+                        frontmatter["version"] = self._bump_version(frontmatter.get("version", "0.1.0"))
                         frontmatter["updated"] = datetime.now().strftime("%Y-%m-%d")
 
                     # Reconstruct the file
                     new_frontmatter = yaml.dump(frontmatter, default_flow_style=False)
-                    new_content = f"---\n{new_frontmatter}---{content[end_marker+3:]}"
+                    new_content = f"---\n{new_frontmatter}---{content[end_marker + 3 :]}"
 
                     # Write back to file
                     with open(spec_file, "w", encoding="utf-8") as f:
@@ -247,7 +223,7 @@ class SpecStatusManager:
         """
         return self.validation_criteria.copy()
 
-    def validate_spec_for_completion(self, spec_id: str) -> Dict:
+    def validate_spec_for_completion(self, spec_id: str) -> Dict[str, Any]:
         """Validate if a SPEC is ready for completion
 
         Args:
@@ -262,7 +238,7 @@ class SpecStatusManager:
                 'recommendations': List[str]
             }
         """
-        result = {
+        result: Dict[str, Any] = {
             "is_ready": False,
             "criteria_met": {},
             "issues": [],
@@ -274,68 +250,74 @@ class SpecStatusManager:
             spec_file = spec_dir / "spec.md"
 
             if not spec_file.exists():
-                result["issues"].append(f"SPEC file not found: {spec_file}")
+                issues_list = result["issues"]
+                if isinstance(issues_list, list):
+                    issues_list.append(f"SPEC file not found: {spec_file}")
                 return result
 
             # Check implementation status
-            criteria_checks = {}
+            criteria_checks: Dict[str, bool] = {}
 
             # Check for code implementation
             spec_dir = spec_file.parent
             src_dir = spec_dir.parent.parent / "src"
-            criteria_checks["code_implemented"] = (
-                src_dir.exists() and len(list(src_dir.rglob("*.py"))) > 0
-            )
+            criteria_checks["code_implemented"] = src_dir.exists() and len(list(src_dir.rglob("*.py"))) > 0
             if not criteria_checks["code_implemented"]:
-                result["issues"].append("No source code files found")
+                issues_list = result["issues"]
+                if isinstance(issues_list, list):
+                    issues_list.append("No source code files found")
 
             # Check for test implementation
             test_dir = spec_dir.parent.parent / "tests"
             test_files = list(test_dir.rglob("test_*.py")) if test_dir.exists() else []
             criteria_checks["test_implemented"] = len(test_files) > 0
             if not criteria_checks["test_implemented"]:
-                result["issues"].append("No test files found")
+                issues_list = result["issues"]
+                if isinstance(issues_list, list):
+                    issues_list.append("No test files found")
 
             # Check for acceptance criteria
-            criteria_checks["tasks_completed"] = self._check_acceptance_criteria(
-                spec_file
-            )
+            criteria_checks["tasks_completed"] = self._check_acceptance_criteria(spec_file)
             if not criteria_checks["tasks_completed"]:
-                result["issues"].append("Missing acceptance criteria section")
+                issues_list = result["issues"]
+                if isinstance(issues_list, list):
+                    issues_list.append("Missing acceptance criteria section")
 
             # 4. Acceptance criteria present
-            criteria_checks["has_acceptance_criteria"] = (
-                self._check_acceptance_criteria(spec_file)
-            )
+            criteria_checks["has_acceptance_criteria"] = self._check_acceptance_criteria(spec_file)
             if (
                 not criteria_checks["has_acceptance_criteria"]
                 and self.validation_criteria["require_acceptance_criteria"]
             ):
-                result["issues"].append("Missing acceptance criteria section")
+                issues_list = result["issues"]
+                if isinstance(issues_list, list):
+                    issues_list.append("Missing acceptance criteria section")
 
             # 5. Documentation sync
             criteria_checks["docs_synced"] = self._check_documentation_sync(spec_id)
             if not criteria_checks["docs_synced"]:
-                result["recommendations"].append(
-                    "Consider running /alfred:3-sync to update documentation"
-                )
+                recs_list = result["recommendations"]
+                if isinstance(recs_list, list):
+                    recs_list.append("Consider running /moai:3-sync to update documentation")
 
             result["criteria_met"] = criteria_checks
             result["is_ready"] = all(criteria_checks.values())
 
             # Add recommendations
             if result["is_ready"]:
-                result["recommendations"].append(
-                    "SPEC is ready for completion. Consider updating status to 'completed'"
-                )
+                recs_list = result["recommendations"]
+                if isinstance(recs_list, list):
+                    recs_list.append("SPEC is ready for completion. Consider updating status to 'completed'")
 
         except Exception as e:
             logger.error(f"Error validating SPEC {spec_id}: {e}")
-            result["issues"].append(f"Validation error: {e}")
+            issues_list = result["issues"]
+            if isinstance(issues_list, list):
+                issues_list.append(f"Validation error: {e}")
 
         return result
 
-    def batch_update_completed_specs(self) -> Dict:
+    def batch_update_completed_specs(self) -> Dict[str, List[str]]:
         """Batch update all draft SPECs that have completed implementations
 
         Returns:
@@ -346,7 +328,7 @@ class SpecStatusManager:
                 'skipped': List[str]   # Incomplete SPEC IDs
             }
         """
-        results = {"updated": [], "failed": [], "skipped": []}
+        results: Dict[str, List[str]] = {"updated": [], "failed": [], "skipped": []}
 
         draft_specs = self.detect_draft_specs()
         logger.info(f"Checking {len(draft_specs)} draft SPECs for completion")
@@ -359,23 +341,31 @@ class SpecStatusManager:
                 if validation["is_ready"]:
                     # Update status
                     if self.update_spec_status(spec_id, "completed"):
-                        results["updated"].append(spec_id)
+                        updated_list = results["updated"]
+                        if isinstance(updated_list, list):
+                            updated_list.append(spec_id)
                         logger.info(f"Updated SPEC {spec_id} to completed")
                     else:
-                        results["failed"].append(spec_id)
+                        failed_list = results["failed"]
+                        if isinstance(failed_list, list):
+                            failed_list.append(spec_id)
                         logger.error(f"Failed to update SPEC {spec_id}")
                 else:
-                    results["skipped"].append(spec_id)
-                    logger.debug(
-                        f"SPEC {spec_id} not ready for completion: {validation['issues']}"
-                    )
+                    skipped_list = results["skipped"]
+                    if isinstance(skipped_list, list):
+                        skipped_list.append(spec_id)
+                    logger.debug(f"SPEC {spec_id} not ready for completion: {validation['issues']}")
 
             except Exception as e:
-                results["failed"].append(spec_id)
+                failed_list = results["failed"]
+                if isinstance(failed_list, list):
+                    failed_list.append(spec_id)
                 logger.error(f"Error processing SPEC {spec_id}: {e}")
 
         logger.info(
-            f"Batch update complete: {len(results['updated'])} updated, {len(results['failed'])} failed, {len(results['skipped'])} skipped"
+            f"Batch update complete: {len(results['updated'])} updated, "
+            f"{len(results['failed'])} failed, "
+            f"{len(results['skipped'])} skipped"
         )
         return results
 

moai_adk/core/template/backup.py

@@ -5,7 +5,9 @@ Creates and manages backups to protect user data during template updates.
 
 from __future__ import annotations
 
+import re
 import shutil
+from datetime import datetime
 from pathlib import Path
 
 
@@ -41,24 +43,20 @@ class TemplateBackup:
         Returns:
             True when any tracked file exists.
         """
-        return any(
-            (self.target_path / item).exists()
-            for item in [".moai", ".claude", ".github", "CLAUDE.md"]
-        )
+        return any((self.target_path / item).exists() for item in [".moai", ".claude", ".github", "CLAUDE.md"])
 
     def create_backup(self) -> Path:
-        """Create a single backup (always at .moai-backups/backup/).
+        """Create a timestamped backup under .moai-backups/.
 
-        Existing backups are overwritten to maintain only one backup copy.
+        Creates a new timestamped backup directory for each update.
+        Maintains backward compatibility by supporting both new and legacy structures.
 
         Returns:
-            Backup path (always .moai-backups/backup/).
+            Path to timestamped backup directory (e.g., .moai-backups/20241201_143022/).
         """
-        backup_path = self.target_path / ".moai-backups" / "backup"
-
-        # Remove existing backup if present
-        if backup_path.exists():
-            shutil.rmtree(backup_path)
+        # Generate timestamp for backup directory name
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+        backup_path = self.target_path / ".moai-backups" / timestamp
 
         backup_path.mkdir(parents=True, exist_ok=True)
 
@@ -80,6 +78,35 @@ class TemplateBackup:
 
         return backup_path
 
+    def get_latest_backup(self) -> Path | None:
+        """Get the most recent backup, supporting both new and legacy structures.
+
+        Searches for backups in order of preference:
+        1. Latest timestamped backup (new structure)
+        2. Legacy backup/ directory (old structure)
+
+        Returns:
+            Path to the most recent backup directory, or None if no backups exist.
+        """
+        # Check for new timestamped backups first
+        backup_dir = self.target_path / ".moai-backups"
+        if backup_dir.exists():
+            # Match pattern: YYYYMMDD_HHMMSS (8 digits + underscore + 6 digits)
+            timestamp_pattern = re.compile(r"^\d{8}_\d{6}$")
+            timestamped_backups = [d for d in backup_dir.iterdir() if d.is_dir() and timestamp_pattern.match(d.name)]
+
+            if timestamped_backups:
+                # Sort by name (timestamp) and return the latest
+                latest_backup = max(timestamped_backups, key=lambda x: x.name)
+                return latest_backup
+
+        # Fall back to legacy backup/ directory
+        legacy_backup = backup_dir / "backup"
+        if legacy_backup.exists():
+            return legacy_backup
+
+        return None
+
     def _copy_exclude_protected(self, src: Path, dst: Path) -> None:
         """Copy backup content while excluding protected paths.
 
@@ -94,10 +121,7 @@ class TemplateBackup:
             rel_path_str = str(rel_path)
 
             # Skip excluded paths
-            if any(
-                rel_path_str.startswith(exclude_dir)
-                for exclude_dir in self.BACKUP_EXCLUDE_DIRS
-            ):
+            if any(rel_path_str.startswith(exclude_dir) for exclude_dir in self.BACKUP_EXCLUDE_DIRS):
                 continue
 
             dst_item = dst / rel_path
@@ -112,18 +136,19 @@ class TemplateBackup:
 
         Restores .moai, .claude, .github directories and CLAUDE.md file
         from a backup created by create_backup().
+        Supports both new timestamped and legacy backup structures.
 
         Args:
             backup_path: Backup path to restore from.
-                        Defaults to .moai-backups/backup/
+                        If None, automatically finds the latest backup.
 
         Raises:
-            FileNotFoundError: When backup_path doesn't exist.
+            FileNotFoundError: When no backup is found.
         """
         if backup_path is None:
-            backup_path = self.backup_dir / "backup"
+            backup_path = self.get_latest_backup()
 
-        if not backup_path.exists():
+        if backup_path is None or not backup_path.exists():
             raise FileNotFoundError(f"Backup not found: {backup_path}")
 
         # Restore each item from backup