Integrate validation and locking into PM commands

[t3chn]

Task: Integrate validation and locking into PM commands

Description

Wire validation scripts and locking mechanisms into existing PM commands, and replace GitHub CLI calls with rate-limit-safe wrapper in bulk operations.

Acceptance Criteria

• Add frontmatter validation to /pm:epic-sync before GitHub operations
• Add frontmatter validation to /pm:sync before GitHub operations
• Add frontmatter validation to /pm:validate command
• Wrap /pm:issue-start with file locking using issue ID
• Replace gh calls with gh_safe in /pm:epic-sync
• Replace gh calls with gh_safe in /pm:sync
• Replace gh calls with gh_safe in /pm:epic-oneshot
• Lock acquisition/release properly handles errors and cleanup
• Validation failures prevent GitHub sync operations
• All existing command signatures remain unchanged

Technical Details

Implementation approach:

• Add validation prolog to sync commands before any GitHub operations
• Wrap issue-start with lock acquire at beginning and release at end/error
• Replace gh command calls with gh_safe in bulk operation scripts
• Ensure proper error handling and cleanup for all integrations

Key considerations:

• Backward compatibility: no changes to command interfaces
• Proper error propagation from validation and locking
• Lock cleanup on script interruption (trap handlers)
• Integration points must be minimal and non-invasive

Code locations/files affected:

• Modify: .claude/scripts/pm/epic-sync.sh
• Modify: .claude/scripts/pm/sync.sh
• Modify: .claude/scripts/pm/validate.sh
• Modify: .claude/scripts/pm/issue-start.sh
• Modify: .claude/scripts/pm/epic-oneshot.sh

Dependencies

• Task 001: validate-frontmatter.sh must be completed and tested
• Task 002: lock script must be completed and tested
• Task 003: gh_safe wrapper must be completed and tested
• Understanding of existing PM command implementations
• Testing environment with GitHub API access

Effort Estimate

• Size: M
• Hours: 2 hours
• Parallel: false (depends on core scripts being completed)

Definition of Done

• All PM commands integrate validation and locking as specified
• Integration preserves existing command behavior and signatures
• Error handling properly propagates failures and cleans up locks
• Manual testing of each modified command verifies functionality
• Validation failures properly prevent GitHub operations
• Lock conflicts properly prevent concurrent issue operations
• gh_safe integration eliminates rate limit failures in bulk operations
• Rollback capability verified (removal of integration lines)

[t3chn]

🔄 Progress Update - 2025-09-08

✅ Completed Work

• Stream A: Validation Integration - ✅ FULLY COMPLETED

  • Enhanced /pm:validate command with validate-frontmatter.sh integration
  • Added validation prolog to /pm:epic-sync before GitHub operations
  • Added validation prolog to /pm:sync before GitHub operations
  • All validation failures properly prevent GitHub sync operations
  • Backward compatibility maintained for all command signatures
  • Fail-fast pattern with exit code 2 for validation errors

• Stream B: Locking & Rate Limiting Integration - ✅ FULLY COMPLETED

  • Wrapped /pm:issue-start with file locking using issue ID
  • Complete trap handler implementation for lock cleanup (EXIT, INT, TERM)
  • Replaced all gh calls with gh_safe in bulk operations:
    • epic-sync.sh: All GitHub CLI operations use rate-limited wrapper
    • sync.sh: All GitHub CLI operations use rate-limited wrapper
    • epic-oneshot.sh: Uses epic-sync.sh with gh_safe integration
  • Lock acquisition/release with proper error handling and cleanup
  • 30-minute TTL for safety with automatic cleanup

🔄 In Progress

• No active work streams - All integration work complete

📝 Technical Notes

• Non-invasive Integration: All validation added as step 0 in sync commands
• Lock Management: Uses "issue-${ISSUE_NUMBER}" pattern for lock naming
• Rate Limiting: gh_safe wrapper protects against GitHub API limits
• Error Propagation: Proper exit codes and error messages maintained
• Cleanup Mechanisms: Trap handlers ensure locks released on interruption

📊 Acceptance Criteria Status

• ✅ Add frontmatter validation to /pm:epic-sync before GitHub operations
• ✅ Add frontmatter validation to /pm:sync before GitHub operations
• ✅ Add frontmatter validation to /pm:validate command
• ✅ Wrap /pm:issue-start with file locking using issue ID
• ✅ Replace gh calls with gh_safe in /pm:epic-sync
• ✅ Replace gh calls with gh_safe in /pm:sync
• ✅ Replace gh calls with gh_safe in /pm:epic-oneshot
• ✅ Lock acquisition/release properly handles errors and cleanup
• ✅ Validation failures prevent GitHub sync operations
• ✅ All existing command signatures remain unchanged

🚀 Next Steps

• Ready for system testing - All integration work complete
• Issue can be closed - All acceptance criteria satisfied
• Available for use - Enhanced PM commands with validation and locking

⚠️ Blockers

• No blockers - All implementation complete and functional

💻 Recent Implementation

• 4 key PM scripts enhanced with validation and locking:
  • issue-start.sh (5,125 bytes) - File locking with trap handlers
  • epic-sync.sh (10,273 bytes) - gh_safe integration + validation
  • sync.sh (10,499 bytes) - gh_safe integration + validation
  • epic-oneshot.sh (3,821 bytes) - Orchestration with enhanced components
• Integration Quality: All existing command signatures preserved
• Error Recovery: Comprehensive cleanup and error propagation
• Testing: Lock functionality and validation workflows verified

---

Progress: 100% | Synced from parallel agent execution at 2025-09-08T18:19:33Z

[t3chn]

✅ Task Completed - 2025-09-08

🎯 All Acceptance Criteria Met

• ✅ Add frontmatter validation to /pm:epic-sync before GitHub operations
• ✅ Add frontmatter validation to /pm:sync before GitHub operations
• ✅ Add frontmatter validation to /pm:validate command
• ✅ Wrap /pm:issue-start with file locking using issue ID
• ✅ Replace gh calls with gh_safe in /pm:epic-sync
• ✅ Replace gh calls with gh_safe in /pm:sync
• ✅ Replace gh calls with gh_safe in /pm:epic-oneshot
• ✅ Lock acquisition/release properly handles errors and cleanup
• ✅ Validation failures prevent GitHub sync operations
• ✅ All existing command signatures remain unchanged

📦 Deliverables

Enhanced PM Commands with Validation & Locking:

• issue-start.sh (5,125 bytes) - File locking with issue ID, trap handlers for cleanup
• epic-sync.sh (10,273 bytes) - Validation prolog + gh_safe rate limiting
• sync.sh (10,499 bytes) - Validation prolog + gh_safe rate limiting
• epic-oneshot.sh (3,821 bytes) - Orchestration using enhanced components
• validate.sh - Enhanced with validate-frontmatter.sh integration

Integration Features:

• Frontmatter Validation: Prevents GitHub sync on invalid YAML
• File Locking: Prevents concurrent issue operations using lock files
• Rate Limiting: Protects against GitHub API limits with gh_safe wrapper
• Error Handling: Proper cleanup and error propagation throughout

🧪 Testing

• Integration tests: ✅ All enhanced commands preserve original signatures
• Validation tests: ✅ Validation failures properly prevent GitHub operations
• Locking tests: ✅ Concurrent access prevention verified
• Rate limiting tests: ✅ gh_safe wrapper integration tested
• Error handling tests: ✅ Trap handlers and cleanup mechanisms verified

📚 Documentation

• Command integration: ✅ Non-invasive prologs added to sync commands
• Interface preservation: ✅ All existing command signatures unchanged
• Error patterns: ✅ Consistent error handling and reporting implemented

🏆 Key Technical Achievements

• Backward Compatibility: Zero breaking changes to existing workflows
• Non-invasive Integration: Validation and locking added as prologs
• Robust Error Handling: Comprehensive cleanup and error propagation
• Performance: Minimal overhead with fail-fast validation patterns
• Safety: File locking prevents race conditions in parallel operations

This task delivers production-ready PM command enhancements with validation, locking, and rate limiting while maintaining full backward compatibility. The integration is complete and ready for use.

---

Task completed: 100% | Final sync at 2025-09-08T18:19:33Z