[plan] Add pre-commit hook and developer documentation

[github-actions]

Objective

Create a git pre-commit hook that warns developers when committing workflow .md files without updated .lock.yml files. Update developer documentation with workflow lifecycle best practices and troubleshooting guidance.

Context

Developers can commit stale workflows without realizing it, only discovering the issue in CI. A pre-commit hook catches this early, and comprehensive documentation helps developers understand workflow lifecycle management.

Approach

1. Create Pre-commit Hook

File: scripts/hooks/pre-commit

Functionality:

• Detect .md files being committed in .github/workflows/
• Check if corresponding .lock.yml exists and is up-to-date
• Warn about stale workflows with actionable command
• Configurable blocking via GH_AW_BLOCK_STALE_COMMITS env var

Default behavior: Warn but don't block (developer-friendly)

Strict mode: export GH_AW_BLOCK_STALE_COMMITS=true blocks commits

Output example:

🔍 Checking workflow compilation status...
⚠️  my-workflow.md has no compiled .lock.yml file
⚠️  other-workflow.lock.yml is older than other-workflow.md

⚠️  2 workflow file(s) need compilation
Run: gh aw compile --all

💡 To block commits with stale workflows: export GH_AW_BLOCK_STALE_COMMITS=true

2. Update CONTRIBUTING.md

Add section covering:

• Workflow compilation requirements
• Pre-commit hook installation instructions
• CI enforcement expectations
• Best practice: compile before committing
• Using bulk commands for efficiency

3. Update DEVGUIDE.md

Add "Workflow Lifecycle Management" section:

• Understanding .md and .lock.yml relationship
• When to recompile (source changes, imports modified)
• Using status command to check compilation state
• Bulk operations for repository-wide management
• Troubleshooting common staleness issues
• Interpreting hash vs timestamp mismatches

4. Installation Instructions

Add to docs:

# Install pre-commit hook
ln -s ../../scripts/hooks/pre-commit .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

# Test the hook
git add .github/workflows/test.md
git commit -m "test"  # Should show warning

Files to Create/Modify

• scripts/hooks/pre-commit - New bash script
• CONTRIBUTING.md - Add compilation requirements section
• DEVGUIDE.md - Add lifecycle management section
• docs/ - Add troubleshooting guide if needed

Acceptance Criteria

• Pre-commit hook checks workflow compilation status
• Hook warns about stale/missing lock files
• Hook provides actionable commands
• Configurable blocking behavior via env var
• Installation instructions in CONTRIBUTING.md
• Comprehensive lifecycle documentation in DEVGUIDE.md
• Troubleshooting section for common issues
• Hook tested with various commit scenarios
• Documentation includes examples and best practices
  Related to [plan] Workflow Lifecycle Management & Staleness Detection Improvements #6181

AI generated by Plan Command for discussion #6133