[DevTools] Migrate from phpro/grumphp to phpro/grumphp-shim and enhance git workflow integration (#issue_number)

[coisa]

Problem

Currently, phpro/grumphp is installed as a direct dependency in composer.json. This approach can cause dependency resolution conflicts because:

• The direct dependency pulls in its full transitive dependency tree
• This can block versions of other packages during composer install or composer update
• The locked versions may conflict with project-specific requirements in other repositories that consume this package

Additionally, the current GrumPHP configuration is limited to pre-commit hooks only, without handling branch-based dependency synchronization.

Proposal

Migrate from phpro/grumphp to phpro/grumphp-shim and enhance the git workflow integration to provide a more robust development experience:

1. Switch to grumphp-shim: Replace the direct phpro/grumphp dependency with phpro/grumphp-shim, which is a no-dependency metapackage that provides the GrumPHP executable without forcing specific dependency versions
2. Add post-checkout hook: Ensure vendor dependencies reflect the correct state for the current branch after checkout
3. Add post-merge hook: Re-install dependencies after merge operations to stay synchronized

Goals

• Eliminate dependency resolution conflicts caused by phpro/grumphp transitive dependencies
• Ensure vendor state stays synchronized with branch-specific composer.lock after branch switches
• Maintain the existing pre-commit validation while improving the overall git workflow integration

Expected Behavior

After this change:

1. Installing fast-forward/dev-tools will no longer impose version constraints from phpro/grumphp transitive dependencies
2. When switching branches, the post-checkout hook will check if composer.lock changed and run composer install if needed
3. After merging branches, the post-merge hook will ensure dependencies are up-to-date
4. Pre-commit hooks continue to run composer dev-tools validation before commits are allowed

Implementation Strategy

1. Replace phpro/grumphp with phpro/grumphp-shim in composer.json require section
2. Update the grumphp.yml configuration to include additional git hooks
3. Add stop_on_failure: true to maintain the current behavior
4. Test the migration to ensure backward compatibility

composer.json changes

- "phpro/grumphp": "^2.19",
+ "phpro/grumphp-shim": "^0.1.0",

grumphp.yml enhancements

• Add composer_checker_task (optional): Check if composer.json and composer.lock are synchronized
• Add git hook configuration for post-checkout and post-merge
• These hooks should:
  1. Check if composer.lock was modified
  2. Run composer install --no-interaction if needed

Additional Enhancements (Suggested)

The following enhancements could improve the GrumPHP integration beyond the core requirement:

Enhancement	Description	Priority
Parallel task execution	Run independent tasks in parallel for faster validation	Low
Task caching	Cache task results to speed up subsequent runs	Medium
Enhanced emoji output	Use emoji in console output for better visual feedback	Low
Custom task configuration	Allow repository-specific task overrides	Medium

Non-goals

• Does NOT change: The existing pre-commit validation behavior
• Does NOT add: New validation rules beyond what dev-tools already provides
• Does NOT modify: The core plugin functionality of dev-tools

Benefits

1. Better dependency resolution: Eliminates version conflicts in downstream projects
2. Synchronized vendor state: Ensures developers always have the correct dependencies for the current branch
3. Improved DX: Automatic synchronization reduces manual intervention when switching contexts

Acceptance Criteria

Functional Criteria

• phpro/grumphp-shim is installed instead of phpro/grumphp
• Pre-commit hooks still run composer dev-tools before commits are accepted
• Post-checkout hook runs composer install when composer.lock changes
• Post-merge hook runs composer install after merge operations
• The migration does not break existing installations

Verification Commands

# Verify grumphp-shim is installed
composer show phpro/grumphp-shim

# Test pre-commit validation (should fail without --no-verify)
echo "invalid php" > /tmp/test.php
git add /tmp/test.php
# grumphp should catch this in pre-commit

# Verify git hooks are registered
cat .git/hooks/pre-commit | head -5
cat .git/hooks/post-checkout | head -5
cat .git/hooks/post-merge | head -5

Architectural / Isolation Criteria

• MUST: The GrumPHP configuration MUST be isolated in grumphp.yml as a declarative configuration file.
• MUST: Any custom tasks or extensions MUST be implemented as separate classes in src/GrumPHP/ following the existing namespace conventions.
• MUST: The implementation MUST allow GrumPHP to be disabled or overridden in consuming projects without breaking functionality.