Monitor Smart Validator

Validates git repository state and branch policies after every file modification, ensuring changes comply with workflow rules before commits.

When to Use This Hook

Attach this hook when you need to:

• Continuously validate that file modifications comply with branch protection rules and merge policies during development
• Detect when changes are being made on protected branches and alert developers to switch to feature branches before committing
• Track the cumulative scope of changes and warn when a single branch accumulates too many modifications for a clean pull request

Consider alternatives when:

• Your git hosting platform enforces branch protection rules server-side and client-side validation is redundant
• You use a trunk-based development workflow where all changes go directly to the main branch by design

Quick Start

Configuration

Copy
name: monitor-smart-validator
type: hook
trigger: PostToolUse
category: git-workflow

Example Trigger

Copy
# Claude edits a file while on the main branch:
# Edit tool modifies src/app.ts
# Hook fires:
# Smart Validator: Checking git workflow compliance...

Example Output

Smart Validator: Git Workflow Report
Current Branch: main
Branch Policy: PROTECTED (direct commits discouraged)
Recommendation: Create a feature branch before committing
Uncommitted Changes: 3 files modified
  - src/app.ts (14 lines changed)
  - src/utils/helper.ts (8 lines changed)
  - package.json (2 lines changed)
Change Scope: Small (24 lines across 3 files)
PR Readiness: Changes are PR-sized and focused
Status: WARNING - switch to feature branch

Core Concepts

Smart Validation Overview

Aspect	Details
Trigger Point	PostToolUse on Edit, MultiEdit, and Write operations
Branch Detection	Identifies current branch and checks against protected branch list
Change Tracking	Accumulates modification counts across the session
Scope Analysis	Classifies change scope as small, medium, or large for PR guidance
Protected Branches	Configurable list of branches that should not receive direct commits
Alert Type	Warning-level output to stderr without blocking the workflow

Validation Workflow

PostToolUse (Edit/MultiEdit/Write)
    |
    v
[Is this a git repository?] --No--> [Skip]
    |
   Yes
    |
    v
[Get current branch name]
    |
    v
[Is branch in protected list?]
    |          |
   No         Yes
    |          |
[Check      [Output branch warning]
 scope]        |
    |          v
    v     [Suggest feature branch]
[Count changed files and lines]
    |
    v
[Classify scope: small/medium/large]
    |
    v
[Output workflow compliance report]

Configuration

Parameter	Type	Default	Description
protected_branches	string	main|master|develop	Pipe-separated list of branches that should not receive direct commits
scope_medium_threshold	integer	100	Lines changed threshold for classifying scope as medium
scope_large_threshold	integer	500	Lines changed threshold for classifying scope as large
block_protected	boolean	false	Whether to block edits on protected branches with exit code 2
track_session_scope	boolean	true	Whether to accumulate and report total session change scope

Best Practices

1. Keep the validator in warning mode initially - Set block_protected to false when first deploying so developers are warned but not blocked. This allows the team to adapt their workflow to branch policies without immediate friction.

2. Use scope analysis for PR planning - When the validator reports a large change scope, consider splitting the work into multiple focused branches and PRs. Smaller PRs are easier to review and less likely to cause merge conflicts.

3. Customize protected branches for your workflow - Add all branches that should not receive direct commits to the protected_branches list. This typically includes main, master, develop, and release branches.

4. Monitor scope growth during sessions - If the session scope tracker shows rapid growth, it may indicate scope creep. Pause to review whether the changes are focused on the intended task or if unrelated modifications are being introduced.

5. Integrate with branch naming conventions - Extend the validator to check branch naming conventions like feature/, bugfix/, or hotfix/ prefixes. This provides additional workflow guidance beyond just protected branch detection.

Common Issues

1. Validator warns on every edit when working on main - If you intentionally work on main for small fixes, the constant warnings can be distracting. Either create a feature branch as suggested, or temporarily disable the protected branch check for the session.

2. Change scope count is inaccurate for refactoring - Large-scale refactoring may trigger the large scope warning even though the changes are mechanical and low-risk. The validator uses line counts which do not distinguish between risky logic changes and safe refactoring.

3. Validator does not detect stashed changes - The scope tracker only counts unstaged and staged modifications visible to git status. Stashed changes are not included in the scope calculation, which may undercount the total changes in progress.