moai-adk 0.34.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-workflow-worktree/modules/registry-architecture.md

@@ -0,0 +1,271 @@
+# Registry Architecture Module
+
+Purpose: Detailed registry structure, atomic operations, concurrent access protection, and validation patterns for worktree metadata management.
+
+Version: 1.0.0
+Last Updated: 2026-01-06
+
+---
+
+## Quick Reference (30 seconds)
+
+Registry Components:
+- File Location: ~/.worktrees/{PROJECT_NAME}/.moai-worktree-registry.json
+- Format: JSON with versioned schema
+- Operations: Atomic updates with backup and rollback
+- Concurrency: File-based locking for multi-process safety
+
+---
+
+## Registry Schema
+
+### Complete Registry Structure
+
+The registry file contains these top-level sections:
+
+Version and Timestamps:
+- version: Schema version string (e.g., "1.0.0")
+- created_at: ISO 8601 timestamp of registry creation
+- last_updated: ISO 8601 timestamp of most recent modification
+
+Configuration Section:
+- worktree_root: Absolute path to worktree base directory
+- auto_sync: Boolean flag for automatic synchronization
+- cleanup_merged: Boolean flag for automatic cleanup
+- default_base: Default base branch name
+- sync_strategy: Preferred sync method (merge, rebase, squash)
+- registry_type: local or team mode
+- max_worktrees: Maximum allowed worktrees
+
+Worktrees Map:
+- Key: SPEC ID (e.g., "SPEC-001")
+- Value: Complete worktree metadata object
+
+Statistics Section:
+- total_worktrees: Count of all registered worktrees
+- active_worktrees: Count of active worktrees
+- merged_worktrees: Count of merged worktrees
+- total_disk_usage: Aggregate storage size
+- last_cleanup: Timestamp of most recent cleanup
+
+### Worktree Entry Schema
+
+Each worktree entry contains nested sections:
+
+Identity Fields:
+- id: SPEC identifier (required)
+- description: Human-readable description (optional)
+- path: Absolute filesystem path (required)
+
+Branch Information:
+- branch: Feature branch name (required)
+- base_branch: Parent branch name (required)
+- status: Current state - active, merged, stale, or error (required)
+- created_at: ISO 8601 creation timestamp (required)
+- last_accessed: ISO 8601 last access timestamp
+- last_sync: ISO 8601 last sync timestamp
+
+Git State (git_info section):
+- commits_ahead: Integer count of commits ahead of base
+- commits_behind: Integer count of commits behind base
+- uncommitted_changes: Boolean indicating uncommitted changes
+- branch_status: ahead, behind, diverged, or up-to-date
+- merge_conflicts: Boolean indicating unresolved conflicts
+
+Metadata (metadata section):
+- template: Template used for creation
+- developer: Developer identifier
+- priority: high, medium, or low
+- estimated_size: Estimated disk usage
+- tags: Array of categorization tags
+
+Operations (operations section):
+- total_syncs: Count of sync operations
+- total_conflicts: Count of conflicts encountered
+- last_operation: Name of most recent operation
+- last_operation_status: success or error
+
+---
+
+## Atomic Operations
+
+### Update Pattern with Backup
+
+All registry updates follow an atomic pattern to prevent corruption.
+
+Update Workflow:
+1. Create backup of current registry with .backup.json suffix
+2. Load current registry into memory
+3. Validate proposed updates against schema
+4. Apply updates to in-memory copy
+5. Write updated registry to temporary file with .tmp.json suffix
+6. Atomic rename of temporary file to registry path
+7. Remove backup file on success
+
+Rollback on Failure:
+- If any step fails, restore from backup file
+- Temporary file is removed on failure
+- Error details are captured and raised
+
+### Validation Before Update
+
+Before applying updates, validate:
+- SPEC ID format matches pattern ^SPEC-[0-9]+$
+- Path uniqueness across all worktrees
+- Required fields are present
+- Timestamp formats are valid ISO 8601
+- Status values are from allowed enum
+
+---
+
+## Concurrent Access Protection
+
+### File Locking
+
+Multiple processes may access the registry simultaneously. Protection uses file-based locking.
+
+Lock Acquisition:
+- Create lock file with .lock suffix
+- Acquire exclusive lock using fcntl
+- Non-blocking attempt first
+- If blocked, retry with timeout (30 seconds default)
+- Raise error if lock cannot be acquired
+
+Lock Release:
+- Execute protected operation within lock context
+- Release lock in finally block
+- Remove lock file after release
+
+### Timeout Handling
+
+If lock cannot be acquired within timeout:
+- Log warning about long-running operation
+- Raise RegistryError with descriptive message
+- Caller can retry or abort
+
+---
+
+## Registry Validation
+
+### Schema Validation
+
+Validate registry structure against JSON Schema.
+
+Top-Level Requirements:
+- Required fields: version, created_at, last_updated, config, worktrees
+- Config must include: worktree_root, default_base
+- Worktrees must be object with valid pattern keys
+
+Worktree Entry Requirements:
+- Required fields: id, path, branch, status, created_at
+- Status must be one of: active, merged, stale, error
+- Timestamps must be valid ISO 8601 format
+
+### Integrity Checks
+
+Beyond schema validation, verify:
+
+Path Existence:
+- Each worktree path must exist on filesystem
+- Each path must contain .git file (worktree marker)
+
+Path Uniqueness:
+- No duplicate paths across worktrees
+- Paths must be canonical (no symlink variations)
+
+Git Repository Validation:
+- Verify worktree is valid Git repository
+- Check branch matches expected value
+- Verify remote tracking configuration
+
+---
+
+## Registry Management Patterns
+
+### Worktree Registration
+
+When registering a new worktree:
+
+Create Entry:
+- Generate worktree entry with all required fields
+- Set initial status to active
+- Set created_at and last_accessed to current timestamp
+- Initialize git_info with current state
+- Initialize operations counters to zero
+
+Update Registry:
+- Add entry to worktrees map
+- Update statistics (increment total_worktrees, active_worktrees)
+- Set last_updated timestamp
+
+### Worktree Update
+
+When updating existing worktree:
+
+Common Updates:
+- last_accessed: Updated on each access
+- last_sync: Updated after sync operation
+- git_info: Refreshed with current Git state
+- operations: Increment counters, update last operation
+
+Status Transitions:
+- active -> merged: When branch merged to base
+- active -> stale: When last_accessed exceeds threshold
+- active -> error: When operation fails
+- any -> active: When worktree recovered
+
+### Worktree Removal
+
+When removing worktree:
+
+Registry Update:
+- Remove entry from worktrees map
+- Update statistics (decrement counters)
+- Optionally record in completed_specs for audit
+
+Cleanup:
+- Remove filesystem path
+- Remove Git worktree reference
+- Delete associated branch if requested
+
+---
+
+## Error Recovery
+
+### Corruption Detection
+
+Detect registry corruption by:
+- JSON parse failure
+- Schema validation failure
+- Missing required sections
+- Invalid data types
+
+### Recovery Options
+
+On Corruption:
+1. Check for backup file (.backup.json)
+2. If backup exists and valid, restore from backup
+3. If no valid backup, scan filesystem for worktrees
+4. Rebuild registry from discovered worktrees
+5. Log recovery actions for audit
+
+### Migration Patterns
+
+When schema version changes:
+
+Version Check:
+- Compare registry version with expected version
+- If older, apply migrations in sequence
+
+Migration Steps:
+- Backup current registry
+- Apply transformation for each version increment
+- Update version field
+- Validate migrated registry
+- Save updated registry
+
+---
+
+Version: 1.0.0
+Last Updated: 2026-01-06
+Module: Registry architecture with schema, operations, and validation patterns

moai_adk/templates/.claude/skills/moai-workflow-worktree/modules/resource-optimization.md

@@ -0,0 +1,300 @@
+# Resource Optimization Module
+
+Purpose: Disk space management, memory-efficient operations, performance optimization, and error handling patterns for worktree management.
+
+Version: 1.0.0
+Last Updated: 2026-01-06
+
+---
+
+## Quick Reference (30 seconds)
+
+Optimization Areas:
+- Disk Space: Analysis, cleanup, and compression strategies
+- Memory: Streaming operations and caching patterns
+- Performance: Parallel operations and efficient queries
+- Error Handling: Recovery patterns and resilience
+
+---
+
+## Disk Space Management
+
+### Usage Analysis
+
+Analyze disk usage across all worktrees.
+
+Analysis Components:
+- Per-worktree size calculation (recursive file size sum)
+- Identification of large worktrees exceeding thresholds
+- Detection of excessive build artifacts
+- Comparison against configured limits
+
+Report Contents:
+- total_size: Aggregate size of all worktrees
+- worktree_sizes: Map of SPEC ID to size in bytes
+- large_worktrees: List of worktrees exceeding threshold
+- optimization_suggestions: Recommended cleanup actions
+
+Size Thresholds:
+- Warning threshold: 500MB per worktree
+- Critical threshold: 1GB per worktree
+- Configurable via max_worktree_size setting
+
+### Optimization Strategies
+
+Reduce disk usage through multiple strategies:
+
+Build Artifact Removal:
+- node_modules (recreatable via npm install)
+- dist/build directories (recreatable via build command)
+- .cache directories
+- Compiled files (.pyc, .class)
+
+Cache Cleanup:
+- pytest_cache and __pycache__ directories
+- .npm and .yarn cache
+- IDE index files
+
+Git Repository Optimization:
+- git gc --aggressive --prune=now
+- Remove orphaned objects
+- Compress pack files
+
+Worktree Compression:
+- For inactive worktrees (no access in 90+ days)
+- Create compressed archive
+- Remove original directory
+- Maintain registry entry with archived flag
+
+### Automatic Cleanup
+
+Configure automatic cleanup based on triggers:
+
+Cleanup Triggers:
+- Disk usage exceeds threshold percentage
+- Total worktrees exceed maximum count
+- Individual worktree exceeds size limit
+- Scheduled cleanup interval reached
+
+Cleanup Priority:
+1. Merged worktrees (highest priority)
+2. Stale worktrees (not accessed in N days)
+3. Error state worktrees
+4. Large worktrees with available archives
+
+---
+
+## Memory Efficiency
+
+### Streaming Operations
+
+For large registries, use streaming JSON parsing to avoid loading entire file.
+
+Streaming Pattern:
+- Use incremental JSON parser (ijson)
+- Process worktrees one at a time
+- Apply filters during iteration
+- Yield matching worktrees
+
+Benefits:
+- Constant memory usage regardless of registry size
+- Faster time-to-first-result for queries
+- Reduced memory pressure on constrained systems
+
+### Registry Caching
+
+Implement caching to avoid repeated disk reads.
+
+Cache Configuration:
+- Cache TTL: 5 minutes default
+- Cache invalidation on write operations
+- Lazy loading on first access
+
+Cache Strategy:
+- Store parsed registry in memory
+- Track cache timestamp
+- Refresh when TTL expired or after write
+- Clear cache on explicit invalidation
+
+### Lazy Loading
+
+Defer expensive operations until needed:
+- Git status queries only when status requested
+- Disk usage calculation only when size analysis needed
+- Remote fetch only when sync check requested
+
+---
+
+## Performance Optimization
+
+### Parallel Operations
+
+Execute operations on multiple worktrees concurrently.
+
+Parallel Sync:
+- Identify worktrees needing sync
+- Limit concurrent operations to CPU count or 4 (whichever lower)
+- Execute sync operations in thread pool
+- Aggregate results and report
+
+Parallel Analysis:
+- Disk usage calculation across all worktrees
+- Git status queries for all worktrees
+- Stale detection for all worktrees
+
+Resource Limits:
+- max_concurrent_worktrees based on system resources
+- Memory monitoring during parallel operations
+- Graceful degradation to sequential on resource pressure
+
+### Query Optimization
+
+Optimize common queries:
+
+List Worktrees:
+- Cache full list, apply filters in memory
+- Index by status for fast status queries
+- Sort results in memory after filter
+
+Find by ID:
+- Direct dictionary lookup (O(1))
+- No iteration required
+
+Find Stale:
+- Pre-compute stale threshold date
+- Compare last_accessed timestamps
+
+### Batch Operations
+
+Combine multiple operations for efficiency:
+
+Batch Sync:
+- Fetch all remotes once
+- Apply sync to each worktree
+- Single registry update at end
+
+Batch Cleanup:
+- Identify all candidates first
+- Remove worktrees in parallel
+- Single registry update at end
+
+---
+
+## Error Handling
+
+### Error Hierarchy
+
+Structured error classes for different failure types:
+
+WorktreeError: Base class for all worktree errors
+- message: Human-readable error description
+- context: Additional debugging information
+
+WorktreeCreationError: Errors during worktree creation
+- partial_worktree: Path to incomplete worktree for cleanup
+- creation_step: Step at which creation failed
+
+SynchronizationError: Errors during sync operations
+- sync_state: State at time of failure
+- backup_ref: Git ref for recovery
+
+RegistryError: Errors related to registry operations
+- registry_path: Path to problematic registry
+- operation: Operation that failed
+
+### Recovery Patterns
+
+Recover from common failure scenarios:
+
+Creation Failure Recovery:
+1. Remove partial worktree directory if exists
+2. Remove registry entry if created
+3. Clean up temporary files
+4. Report detailed error for debugging
+
+Sync Failure Recovery:
+1. Check for backup ref in sync state
+2. Reset worktree to backup ref if available
+3. Mark worktree status as error
+4. Set manual intervention flag
+5. Log recovery actions
+
+Registry Corruption Recovery:
+1. Check for backup file
+2. Validate backup file integrity
+3. Restore from backup if valid
+4. Scan filesystem for worktrees if no backup
+5. Rebuild registry from filesystem state
+
+### Resilience Patterns
+
+Build resilience into operations:
+
+Retry Logic:
+- Transient failures (network, lock contention) retry 3 times
+- Exponential backoff between retries
+- Final failure logged and reported
+
+Graceful Degradation:
+- Operations continue despite individual failures
+- Aggregate failures reported at end
+- Partial success is acceptable
+
+Consistency Checks:
+- Periodic registry validation
+- Filesystem consistency checks
+- Automatic repair for common issues
+
+---
+
+## Analytics and Monitoring
+
+### Usage Analytics
+
+Track worktree usage patterns:
+
+Metrics Collected:
+- Worktree creation rate
+- Average worktree lifetime
+- Sync frequency per worktree
+- Conflict rate during sync
+- Disk usage trends
+
+Reporting Intervals:
+- Daily summary
+- Weekly aggregate
+- Monthly trends
+
+### Performance Monitoring
+
+Track operation performance:
+
+Timing Metrics:
+- Creation time per worktree
+- Sync duration per worktree
+- Cleanup duration for batch operations
+
+Resource Metrics:
+- Peak memory during operations
+- Disk I/O during sync
+- Network usage during fetch
+
+### Recommendations Engine
+
+Generate optimization recommendations:
+
+Based on Usage Patterns:
+- Suggest cleanup for low-activity worktrees
+- Recommend sync frequency adjustments
+- Identify unnecessary worktrees
+
+Based on Performance:
+- Suggest disk optimization for slow operations
+- Recommend parallel operation adjustments
+- Identify resource bottlenecks
+
+---
+
+Version: 1.0.0
+Last Updated: 2026-01-06
+Module: Resource optimization patterns for disk, memory, performance, and error handling