[P2] Automated scope explosion detector (git hook)

[rjmurillo-bot]

Context

PR #908 had 95 files changed (20× over healthy limit). Need early warning system for scope explosion.

Problem Statement

No visibility into PR size until creation:

• File count grows incrementally
• No alerts when crossing thresholds
• Large PRs discovered too late
• Splitting is harder after the fact

Proposed Solution

Create git hook that tracks cumulative PR size:

Thresholds:

• 10 files: Warning (suggest reviewing scope)
• 20 files: Strong warning (suggest split/commit)
• 50 files: Block commit (hard limit)

Implementation:

• Track files added since branch diverged from main
• Check after each commit
• Display current count: "PR size: X/10 files"
• Suggest: Split PR or commit current work

Acceptance Criteria

• Git hook created (pre-commit or post-commit)
• Tracks cumulative file count
• Warning at 10, 20 files
• Block at 50 files (hard limit)
• Clear remediation guidance
• Bypass mechanism for justified large PRs (e.g., mass refactor)

Effort Estimate

4 hours

Priority

P2 - Normal (This Quarter)

Related

• Issue [P0] Create pre-PR validation script (Validate-PRReadiness.ps1) #934 (pre-PR validation validates final size)
• PR feat(skill): add reflect skill and auto-learning hook #908 (95 files)
• Root Cause: Scope Creep via Tool Side Effects

References

.agents/retrospective/2026-01-15-pr-908-comprehensive-retrospective.md (lines 1321-1327)

[traycerai]

Plan

Observations

The repo already has .githooks/pre-push (enabled via git config core.hooksPath .githooks) which blocks at 50 files and warns at 20 at push time. The gap is per-commit early warning — developers only discover scope explosion at push or PR creation. The pre-commit hook (.githooks/pre-commit) is a bash wrapper that delegates logic to Python scripts per ADR-042. No .githooks/post-commit exists yet.

Approach

Create a Python helper script (scripts/check_pr_size.py) containing all the logic (ADR-042: Python for new scripts). Wire it into two hooks: pre-commit (for the hard block at 50 files, including staged files in the count) and a new post-commit (for per-commit display and warnings at 10/20 after each commit lands). Both hooks follow the existing bash-wrapper-delegates-to-Python pattern. Update CONTRIBUTING.md to document the new check and bypass.

---

Implementation Steps

1. Create scripts/check_pr_size.py

This is the core logic module. It must:

• Accept a --staged flag (used by pre-commit to include staged files in the cumulative count).
• Resolve the merge-base against main then origin/main as fallback (mirror the logic in .githooks/pre-push lines 150–161).
• Collect files changed since merge-base via git diff --name-only <merge-base>..HEAD.
• When --staged is passed, additionally collect staged files via git diff --cached --name-only --diff-filter=ACMRD and union them with the committed set.
• Deduplicate the combined file list.
• Check the ALLOW_LARGE_PR environment variable; if set to "1", skip the block and print a bypass notice.
• Print a status line: PR size: X files (warn ≥10, block ≥50).
• < 10 files: print a green pass line, exit 0.
• 10–19 files: print a yellow WARNING with "Consider reviewing scope. Suggest splitting if unrelated changes are bundled.", exit 0 (non-blocking).
• 20–49 files: print a yellow WARNING with "Strong warning: PR is large. Strongly suggest splitting or committing current work to a separate branch.", exit 0 (non-blocking).
• ≥ 50 files: print a red ERROR with remediation guidance (see below), exit 1 (blocking).

Remediation guidance for the ≥50 block:

PR size: 52 files — exceeds hard limit of 50.
Split this PR or use ALLOW_LARGE_PR=1 to bypass (mass refactor only).
  git stash                          # stash uncommitted work
  gh pr create                       # open PR with current commits
  git stash pop && git checkout -b feat/part-2

Use subprocess.run with check=False for all git calls (consistent with .claude/hooks/pre_commit_slash_commands.py). Use pathlib.Path and standard library only — no new dependencies.

Exit codes:

Exit	Meaning
0	OK or warning (non-blocking)
1	Hard block (≥50 files)
2	Configuration error (no git, no merge-base)

---

2. Modify .githooks/pre-commit — add PR size hard-block section

Insert a new section after the existing branch validation block (around line 103) and before the staged-file linting checks. Follow the existing if/else pattern used for ruff and actionlint checks (lines 280–300):

• Use set_python_cmd (already defined in the hook at line 160) to locate Python.
• Resolve the script path relative to REPO_ROOT.
• Call scripts/check_pr_size.py --staged.
• Capture the exit code with an if ! guard (compatible with set -e).
• On exit code 1: call record_fail equivalent (set EXIT_STATUS=1) and print the remediation block.
• On exit code 0: the script already printed any warnings; no additional action needed.
• Skip gracefully if Python is unavailable (record_skip).

The section header should read # PR Scope Explosion Guard (Issue #944) for traceability.

---

3. Create .githooks/post-commit

New file, executable (chmod +x). Follow the same bash header pattern as .githooks/pre-push (color helpers, REPO_ROOT detection, set_python_cmd). Key differences from pre-commit:

• No set -e — post-commit must never block (git ignores non-zero exit from post-commit, but it's confusing to users).
• Call scripts/check_pr_size.py (without --staged — the commit is already made).
• Always exit 0 regardless of script output.
• Include the same ADR-005 bash-exception comment as the other hooks.

The header comment should note: "post-commit: informational only. Displays cumulative PR size after each commit. Hard block is enforced by pre-commit."

---

4. Update CONTRIBUTING.md

In the Pre-Commit Hooks section (around line 389), add a bullet:

• PR scope explosion guard: Tracks cumulative files changed since branch diverged from main. Warns at 10 and 20 files; blocks commit at 50 files. Bypass for justified large changes: ALLOW_LARGE_PR=1 git commit.

In the Pre-Push Hooks table, note that the file-count gate also runs at push time (already documented) and that the commit-level gate provides earlier feedback.

Add a new subsection PR Size Thresholds (parallel to the existing Commit Count Thresholds section at line 585):

File Count	Action
< 10	✅ Pass
10–19	⚠️ Warning (review scope)
20–49	⚠️ Strong warning (consider splitting)
≥ 50	❌ Blocked (ALLOW_LARGE_PR=1 to bypass)

---

5. Flow diagram

sequenceDiagram
    participant Dev as Developer
    participant PreCommit as .githooks/pre-commit
    participant Script as scripts/check_pr_size.py
    participant PostCommit as .githooks/post-commit

    Dev->>PreCommit: git commit
    PreCommit->>Script: python check_pr_size.py --staged
    Script->>Script: merge-base(HEAD, main/origin/main)
    Script->>Script: committed_files = diff(merge-base..HEAD)
    Script->>Script: staged_files = git diff --cached
    Script->>Script: total = union(committed, staged)
    alt total < 10
        Script-->>PreCommit: exit 0 (pass)
    else 10 ≤ total < 50
        Script-->>PreCommit: exit 0 + WARNING printed
    else total ≥ 50 and ALLOW_LARGE_PR≠1
        Script-->>PreCommit: exit 1 (block)
        PreCommit-->>Dev: ❌ Commit blocked — split PR or set ALLOW_LARGE_PR=1
    end
    PreCommit-->>Dev: Commit succeeds
    Dev->>PostCommit: (auto-triggered after commit)
    PostCommit->>Script: python check_pr_size.py
    Script-->>PostCommit: PR size: X files
    PostCommit-->>Dev: Informational display (always exit 0)

Loading

Import In IDE

🤖 Prompt for AI Agents

## Observations

The repo already has `.githooks/pre-push` (enabled via `git config core.hooksPath .githooks`) which blocks at 50 files and warns at 20 at **push time**. The gap is **per-commit** early warning — developers only discover scope explosion at push or PR creation. The pre-commit hook (`.githooks/pre-commit`) is a bash wrapper that delegates logic to Python scripts per ADR-042. No `.githooks/post-commit` exists yet.

## Approach

Create a Python helper script (`scripts/check_pr_size.py`) containing all the logic (ADR-042: Python for new scripts). Wire it into two hooks: **pre-commit** (for the hard block at 50 files, including staged files in the count) and a new **post-commit** (for per-commit display and warnings at 10/20 after each commit lands). Both hooks follow the existing bash-wrapper-delegates-to-Python pattern. Update `CONTRIBUTING.md` to document the new check and bypass.

---

## Implementation Steps

### 1. Create `scripts/check_pr_size.py`

This is the core logic module. It must:

- Accept a `--staged` flag (used by pre-commit to include staged files in the cumulative count).
- Resolve the merge-base against `main` then `origin/main` as fallback (mirror the logic in `.githooks/pre-push` lines 150–161).
- Collect files changed since merge-base via `git diff --name-only <merge-base>..HEAD`.
- When `--staged` is passed, additionally collect staged files via `git diff --cached --name-only --diff-filter=ACMRD` and union them with the committed set.
- Deduplicate the combined file list.
- Check the `ALLOW_LARGE_PR` environment variable; if set to `"1"`, skip the block and print a bypass notice.
- Print a status line: `PR size: X files (warn ≥10, block ≥50)`.
- **< 10 files**: print a green pass line, exit 0.
- **10–19 files**: print a yellow `WARNING` with "Consider reviewing scope. Suggest splitting if unrelated changes are bundled.", exit 0 (non-blocking).
- **20–49 files**: print a yellow `WARNING` with "Strong warning: PR is large. Strongly suggest splitting or committing current work to a separate branch.", exit 0 (non-blocking).
- **≥ 50 files**: print a red `ERROR` with remediation guidance (see below), exit 1 (blocking).

Remediation guidance for the ≥50 block:
```
PR size: 52 files — exceeds hard limit of 50.
Split this PR or use ALLOW_LARGE_PR=1 to bypass (mass refactor only).
  git stash                          # stash uncommitted work
  gh pr create                       # open PR with current commits
  git stash pop && git checkout -b feat/part-2
```

Use `subprocess.run` with `check=False` for all git calls (consistent with `.claude/hooks/pre_commit_slash_commands.py`). Use `pathlib.Path` and standard library only — no new dependencies.

Exit codes:
| Exit | Meaning |
|------|---------|
| 0 | OK or warning (non-blocking) |
| 1 | Hard block (≥50 files) |
| 2 | Configuration error (no git, no merge-base) |

---

### 2. Modify `.githooks/pre-commit` — add PR size hard-block section

Insert a new section after the existing branch validation block (around line 103) and before the staged-file linting checks. Follow the existing `if/else` pattern used for ruff and actionlint checks (lines 280–300):

- Use `set_python_cmd` (already defined in the hook at line 160) to locate Python.
- Resolve the script path relative to `REPO_ROOT`.
- Call `scripts/check_pr_size.py --staged`.
- Capture the exit code with an `if !` guard (compatible with `set -e`).
- On exit code 1: call `record_fail` equivalent (set `EXIT_STATUS=1`) and print the remediation block.
- On exit code 0: the script already printed any warnings; no additional action needed.
- Skip gracefully if Python is unavailable (`record_skip`).

The section header should read `# PR Scope Explosion Guard (Issue #944)` for traceability.

---

### 3. Create `.githooks/post-commit`

New file, executable (`chmod +x`). Follow the same bash header pattern as `.githooks/pre-push` (color helpers, `REPO_ROOT` detection, `set_python_cmd`). Key differences from pre-commit:

- **No `set -e`** — post-commit must never block (git ignores non-zero exit from post-commit, but it's confusing to users).
- Call `scripts/check_pr_size.py` (without `--staged` — the commit is already made).
- Always exit 0 regardless of script output.
- Include the same ADR-005 bash-exception comment as the other hooks.

The header comment should note: _"post-commit: informational only. Displays cumulative PR size after each commit. Hard block is enforced by pre-commit."_

---

### 4. Update `CONTRIBUTING.md`

In the **Pre-Commit Hooks** section (around line 389), add a bullet:

> - **PR scope explosion guard**: Tracks cumulative files changed since branch diverged from `main`. Warns at 10 and 20 files; blocks commit at 50 files. Bypass for justified large changes: `ALLOW_LARGE_PR=1 git commit`.

In the **Pre-Push Hooks** table, note that the file-count gate also runs at push time (already documented) and that the commit-level gate provides earlier feedback.

Add a new subsection **PR Size Thresholds** (parallel to the existing **Commit Count Thresholds** section at line 585):

| File Count | Action |
|------------|--------|
| < 10 | ✅ Pass |
| 10–19 | ⚠️ Warning (review scope) |
| 20–49 | ⚠️ Strong warning (consider splitting) |
| ≥ 50 | ❌ Blocked (`ALLOW_LARGE_PR=1` to bypass) |

---

### 5. Flow diagram

```mermaid
sequenceDiagram
    participant Dev as Developer
    participant PreCommit as .githooks/pre-commit
    participant Script as scripts/check_pr_size.py
    participant PostCommit as .githooks/post-commit

    Dev->>PreCommit: git commit
    PreCommit->>Script: python check_pr_size.py --staged
    Script->>Script: merge-base(HEAD, main/origin/main)
    Script->>Script: committed_files = diff(merge-base..HEAD)
    Script->>Script: staged_files = git diff --cached
    Script->>Script: total = union(committed, staged)
    alt total < 10
        Script-->>PreCommit: exit 0 (pass)
    else 10 ≤ total < 50
        Script-->>PreCommit: exit 0 + WARNING printed
    else total ≥ 50 and ALLOW_LARGE_PR≠1
        Script-->>PreCommit: exit 1 (block)
        PreCommit-->>Dev: ❌ Commit blocked — split PR or set ALLOW_LARGE_PR=1
    end
    PreCommit-->>Dev: Commit succeeds
    Dev->>PostCommit: (auto-triggered after commit)
    PostCommit->>Script: python check_pr_size.py
    Script-->>PostCommit: PR size: X files
    PostCommit-->>Dev: Informational display (always exit 0)
```

---

Execution Information

Branch: main
Commit: 94e7a50

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

🔗 Related PRs

#301 - docs: autonomous PR monitoring prompt and retrospective [merged]
#480 - fix(workflow): use files API for PR changed files (resilient to large diffs) [merged]
#484 - feat(workflow): auto-flag PRs exceeding commit threshold [merged]
#562 - feat(qa): add mandatory pre-PR quality gate enforcement [merged]
#853 - docs: Document exit code 2 bypass failure and establish Claude hooks enforcement [merged]

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[github-actions]

Product Requirements Document

Important

This PRD was automatically generated based on issue triage escalation.
Complexity Score: 6/12 (Standard)
Escalation Criteria: feature_request,multi_phase_work

About this PRD

This PRD was generated by the Explainer Agent after the issue was flagged
for detailed analysis. The document is designed to be self-contained - it can
be passed to a separate AI agent instance for implementation without additional
context.

PRD Depth Levels:

• Standard (4-6): Brief analysis, clear requirements
• Detailed (7-9): Research section, blocking questions
• Comprehensive (10-12): Phased implementation, risk analysis

---

I now have sufficient context on the existing infrastructure. Let me create the comprehensive PRD.

The directory exists and has other PRD files. The permission denial was unexpected. Let me output the PRD content directly since I cannot create the file:

PRD: Automated Scope Explosion Detector (Git Hook)

Executive Summary

PR #908 contained 95 files changed (20x the healthy limit of 5 files), discovered only at PR creation time. This pattern repeats because no local guardrail warns developers during incremental commits. This PRD defines a git hook that tracks cumulative PR size and provides graduated warnings (10 files), strong warnings (20 files), and hard blocks (50 files) before scope explosion becomes unmanageable.

Scope	Status	Blocker
Post-commit scope tracking	🟢 READY	None
Graduated threshold warnings	🟢 READY	None
Hard block at 50 files	🟢 READY	None
Bypass mechanism for justified large PRs	🟢 READY	None
Remediation guidance	🟢 READY	None

Verdict: READY - All requirements are well-defined with no external dependencies or blockers.

---

Problem Statement

Current State

Aspect	Current Behavior
PR size visibility	None until gh pr create or GitHub web UI
File accumulation	Grows silently across commits
Developer feedback	Zero during development
Discovery timing	At PR creation (too late to split easily)
Remediation difficulty	High (requires interactive rebase, cherry-pick)

Gap Analysis

The project has extensive pre-commit validation (1200+ lines in .githooks/pre-commit) covering markdown linting, PSScriptAnalyzer, planning artifacts, session protocol, SHA pinning, and token budgets.

Missing: PR scope tracking. No mechanism warns developers when cumulative changes across commits approach problematic thresholds.

User Impact

User Type	Impact
Agent developers	Unaware PR is growing until review comments
Reviewers	Face 95-file PRs requiring hours to review
CI pipeline	Long test runs, increased failure surface
Repository maintainers	Merge conflicts, rollback difficulty

---

Research Findings

Primary Sources

ADR-004: Pre-Commit Hook Architecture (CONFIRMED)

• Pre-commit is the primary validation orchestration point
• Guidelines: "Fast (<2s), local-only, auto-fixable, non-destructive"
• Supports both BLOCKING and WARNING modes

ADR-005: PowerShell-Only Scripting (CONFIRMED)

• All logic must be in PowerShell (.ps1, .psm1)
• Pre-commit hook (bash) is a grandfathered exception
• Hook delegates to PowerShell scripts for all logic

PROJECT-CONSTRAINTS.md (CONFIRMED)

• Commit constraints: "SHOULD limit to max 5 files OR single topic"
• Language constraints: PowerShell mandatory for all scripting

---

Proposed Solution

Phase 1: PowerShell Module (Effort: S)

Task	Description
1.1	Create scripts/Get-PRScopeMetrics.ps1 - Core logic for file counting
1.2	Implement branch divergence detection (git merge-base)
1.3	Return structured output: file count, threshold status, remediation hints
1.4	Create Pester tests in scripts/tests/Get-PRScopeMetrics.Tests.ps1

Phase 2: Pre-commit Hook Integration (Effort: S)

Task	Description
2.1	Add new section to .githooks/pre-commit after Session Protocol validation
2.2	Implement graduated thresholds (10/20/50) with appropriate blocking behavior
2.3	Add bypass mechanism via ALLOW_LARGE_PR=1 environment variable
2.4	Display current count in format "PR size: X/10 files"

Phase 3: Documentation (Effort: XS)

Task	Description
3.1	Update ADR-004 with new validation section
3.2	Document bypass mechanism in hook comments

---

Functional Requirements

FR-1: File Count Tracking (P0)

ID	Requirement	Acceptance Criteria
FR-1.1	MUST track cumulative file count since branch diverged from main	git diff --name-only $(git merge-base HEAD main) returns correct file list
FR-1.2	MUST count unique files only	File list is deduplicated before counting
FR-1.3	MUST work when not on a branch (detached HEAD)	Graceful fallback or skip with warning

FR-2: Threshold Enforcement (P0)

ID	Requirement	Acceptance Criteria
FR-2.1	MUST display warning at 10 files	Yellow warning output appears
FR-2.2	MUST display strong warning at 20 files	Yellow warning with remediation guidance
FR-2.3	MUST block commit at 50 files with EXIT_STATUS=1	Commit is rejected, red error message

FR-3: Bypass Mechanism (P1)

ID	Requirement	Acceptance Criteria
FR-3.1	MUST allow bypass via ALLOW_LARGE_PR=1 environment variable	Commit succeeds even at 50+ files
FR-3.2	MUST log bypass usage with warning	Audit trail: "WARNING: Large PR bypass enabled"

---

Technical Design

PowerShell Module: Get-PRScopeMetrics.ps1

[CmdletBinding()]
param(
    [string]$BaseBranch = 'main',
    [int]$WarnThreshold = 10,
    [int]$StrongWarnThreshold = 20,
    [int]$BlockThreshold = 50
)

$mergeBase = git merge-base HEAD $BaseBranch 2>$null
$changedFiles = git diff --name-only $mergeBase HEAD | Sort-Object -Unique
$fileCount = @($changedFiles).Count

$status = switch ($true) {
    ($fileCount -ge $BlockThreshold) { 'BLOCK' }
    ($fileCount -ge $StrongWarnThreshold) { 'STRONG_WARN' }
    ($fileCount -ge $WarnThreshold) { 'WARN' }
    default { 'OK' }
}

[PSCustomObject]@{
    FileCount = $fileCount
    ThresholdStatus = $status
    Files = @($changedFiles)
    Message = "PR size: $fileCount files"
}

Pre-commit Hook Section

Add after Session Protocol validation (~line 925):

#
# PR Scope Explosion Detection (WARNING at 10/20, BLOCKING at 50)
#
# Bypass: ALLOW_LARGE_PR=1 git commit
# Related: Issue #934 (pre-PR validation), PR #908 (95 files)
#
SCOPE_METRICS_SCRIPT="$REPO_ROOT/scripts/Get-PRScopeMetrics.ps1"

if [ "$CURRENT_BRANCH" != "main" ] && [ "$CURRENT_BRANCH" != "master" ]; then
    if [ "${ALLOW_LARGE_PR:-}" = "1" ]; then
        echo_warning "Large PR bypass enabled (ALLOW_LARGE_PR=1)"
    elif [ -f "$SCOPE_METRICS_SCRIPT" ] && command -v pwsh &> /dev/null; then
        SCOPE_OUTPUT=$(pwsh -NoProfile -File "$SCOPE_METRICS_SCRIPT" 2>&1)
        # Parse output, handle BLOCK/WARN/OK statuses
    fi
fi

---

Risks and Mitigations

Risk	Likelihood	Impact	Mitigation
False positives on legitimate large changes	Medium	Medium	Bypass mechanism with audit logging
Performance impact on commit	Low	Medium	Git operations are fast; target <2s
Developers bypass habitually	Medium	High	Audit trail; team culture

---

Success Metrics

Metric	Target
PRs exceeding 50 files	0 (blocked by default)
PRs exceeding 20 files	Reduced by 50% within 1 month
Hook execution time	<2 seconds added

---

Appendix A: Research Sources

Source	Link
ADR-004: Pre-Commit Hook Architecture	.agents/architecture/ADR-004-pre-commit-hook-architecture.md
ADR-005: PowerShell-Only Scripting	.agents/architecture/ADR-005-powershell-only-scripting.md
PROJECT-CONSTRAINTS.md	.agents/governance/PROJECT-CONSTRAINTS.md
Pre-commit hook	.githooks/pre-commit (1200+ lines)

---

File could not be saved to .agents/planning/PRD-scope-explosion-detector.md due to permission restrictions. Save this content manually or re-run with write permissions.

_{Generated by AI PRD Generation | View Workflow}

[github-actions]

AI Triage Summary

Note

This issue has been automatically triaged by AI agents

What is AI Triage?

This issue was analyzed by AI agents:

• Analyst Agent: Categorizes the issue and suggests appropriate labels
• Roadmap Agent: Aligns the issue with project milestones and priorities
• Explainer Agent (if escalated): Generates comprehensive PRD

Triage Results

Property	Value
Category	enhancement
Labels	["enhancement","area-infrastructure"]
Priority	P2
Milestone	v1.1
PRD Escalation	Generated (see below)

Categorization Analysis

```json
{
  "labels": ["enhancement", "area-infrastructure"],
  "category": "enhancement",
  "confidence": 0.92,
  "reasoning": "Issue proposes a new git hook feature to detect scope explosion, which is infrastructure tooling rather than agent-specific functionality"
}

</details>

<details>
<summary>Roadmap Alignment</summary>

```json
```json
{
  "milestone": "v1.1",
  "priority": "P2",
  "epic_alignment": "",
  "confidence": 0.70,
  "reasoning": "Developer tooling enhancement for scope control; aligns with maintainability theme but no existing epic covers git hooks or PR hygiene.",
  "escalate_to_prd": true,
  "escalation_criteria": ["feature_request", "multi_phase_work"],
  "complexity_score": 6
}

</details>

---

<sub>Powered by [AI Issue Triage](https://github.com/rjmurillo/ai-agents) workflow</sub>

[traycerai]

I have updated the Implementation Plan to reflect the recent changes in the ticket.

New Plan

Observations

The repo already has .githooks/pre-push (enabled via git config core.hooksPath .githooks) which blocks at 50 files and warns at 20 at push time. The gap is per-commit early warning — developers only discover scope explosion at push or PR creation. The pre-commit hook (.githooks/pre-commit) is a bash wrapper that delegates logic to Python scripts per ADR-042. No .githooks/post-commit exists yet.

Approach

Create a Python helper script (scripts/check_pr_size.py) containing all the logic (ADR-042: Python for new scripts). Wire it into two hooks: pre-commit (for the hard block at 50 files, including staged files in the count) and a new post-commit (for per-commit display and warnings at 10/20 after each commit lands). Both hooks follow the existing bash-wrapper-delegates-to-Python pattern. Update CONTRIBUTING.md to document the new check and bypass.

---

Implementation Steps

1. Create scripts/check_pr_size.py

This is the core logic module. It must:

• Accept a --staged flag (used by pre-commit to include staged files in the cumulative count).
• Resolve the merge-base against main then origin/main as fallback (mirror the logic in .githooks/pre-push lines 150–161).
• Collect files changed since merge-base via git diff --name-only <merge-base>..HEAD.
• When --staged is passed, additionally collect staged files via git diff --cached --name-only --diff-filter=ACMRD and union them with the committed set.
• Deduplicate the combined file list.
• Check the ALLOW_LARGE_PR environment variable; if set to "1", skip the block and print a bypass notice.
• Print a status line: PR size: X files (warn ≥10, block ≥50).
• < 10 files: print a green pass line, exit 0.
• 10–19 files: print a yellow WARNING with "Consider reviewing scope. Suggest splitting if unrelated changes are bundled.", exit 0 (non-blocking).
• 20–49 files: print a yellow WARNING with "Strong warning: PR is large. Strongly suggest splitting or committing current work to a separate branch.", exit 0 (non-blocking).
• ≥ 50 files: print a red ERROR with remediation guidance (see below), exit 1 (blocking).

Remediation guidance for the ≥50 block:

PR size: 52 files — exceeds hard limit of 50.
Split this PR or use ALLOW_LARGE_PR=1 to bypass (mass refactor only).
  git stash                          # stash uncommitted work
  gh pr create                       # open PR with current commits
  git stash pop && git checkout -b feat/part-2

Use subprocess.run with check=False for all git calls (consistent with .claude/hooks/pre_commit_slash_commands.py). Use pathlib.Path and standard library only — no new dependencies.

Exit codes:

Exit	Meaning
0	OK or warning (non-blocking)
1	Hard block (≥50 files)
2	Configuration error (no git, no merge-base)

---

2. Modify .githooks/pre-commit — add PR size hard-block section

Insert a new section after the existing branch validation block (around line 103) and before the staged-file linting checks. Follow the existing if/else pattern used for ruff and actionlint checks (lines 280–300):

• Use set_python_cmd (already defined in the hook at line 160) to locate Python.
• Resolve the script path relative to REPO_ROOT.
• Call scripts/check_pr_size.py --staged.
• Capture the exit code with an if ! guard (compatible with set -e).
• On exit code 1: call record_fail equivalent (set EXIT_STATUS=1) and print the remediation block.
• On exit code 0: the script already printed any warnings; no additional action needed.
• Skip gracefully if Python is unavailable (record_skip).

The section header should read # PR Scope Explosion Guard (Issue #944) for traceability.

---

3. Create .githooks/post-commit

New file, executable (chmod +x). Follow the same bash header pattern as .githooks/pre-push (color helpers, REPO_ROOT detection, set_python_cmd). Key differences from pre-commit:

• No set -e — post-commit must never block (git ignores non-zero exit from post-commit, but it's confusing to users).
• Call scripts/check_pr_size.py (without --staged — the commit is already made).
• Always exit 0 regardless of script output.
• Include the same ADR-005 bash-exception comment as the other hooks.

The header comment should note: "post-commit: informational only. Displays cumulative PR size after each commit. Hard block is enforced by pre-commit."

---

4. Update CONTRIBUTING.md

In the Pre-Commit Hooks section (around line 389), add a bullet:

• PR scope explosion guard: Tracks cumulative files changed since branch diverged from main. Warns at 10 and 20 files; blocks commit at 50 files. Bypass for justified large changes: ALLOW_LARGE_PR=1 git commit.

In the Pre-Push Hooks table, note that the file-count gate also runs at push time (already documented) and that the commit-level gate provides earlier feedback.

Add a new subsection PR Size Thresholds (parallel to the existing Commit Count Thresholds section at line 585):

File Count	Action
< 10	✅ Pass
10–19	⚠️ Warning (review scope)
20–49	⚠️ Strong warning (consider splitting)
≥ 50	❌ Blocked (ALLOW_LARGE_PR=1 to bypass)

---

5. Flow diagram

sequenceDiagram
    participant Dev as Developer
    participant PreCommit as .githooks/pre-commit
    participant Script as scripts/check_pr_size.py
    participant PostCommit as .githooks/post-commit

    Dev->>PreCommit: git commit
    PreCommit->>Script: python check_pr_size.py --staged
    Script->>Script: merge-base(HEAD, main/origin/main)
    Script->>Script: committed_files = diff(merge-base..HEAD)
    Script->>Script: staged_files = git diff --cached
    Script->>Script: total = union(committed, staged)
    alt total < 10
        Script-->>PreCommit: exit 0 (pass)
    else 10 ≤ total < 50
        Script-->>PreCommit: exit 0 + WARNING printed
    else total ≥ 50 and ALLOW_LARGE_PR≠1
        Script-->>PreCommit: exit 1 (block)
        PreCommit-->>Dev: ❌ Commit blocked — split PR or set ALLOW_LARGE_PR=1
    end
    PreCommit-->>Dev: Commit succeeds
    Dev->>PostCommit: (auto-triggered after commit)
    PostCommit->>Script: python check_pr_size.py
    Script-->>PostCommit: PR size: X files
    PostCommit-->>Dev: Informational display (always exit 0)

Loading

Import In IDE

🤖 Prompt for AI Agents

## Observations

The repo already has `.githooks/pre-push` (enabled via `git config core.hooksPath .githooks`) which blocks at 50 files and warns at 20 at **push time**. The gap is **per-commit** early warning — developers only discover scope explosion at push or PR creation. The pre-commit hook (`.githooks/pre-commit`) is a bash wrapper that delegates logic to Python scripts per ADR-042. No `.githooks/post-commit` exists yet.

## Approach

Create a Python helper script (`scripts/check_pr_size.py`) containing all the logic (ADR-042: Python for new scripts). Wire it into two hooks: **pre-commit** (for the hard block at 50 files, including staged files in the count) and a new **post-commit** (for per-commit display and warnings at 10/20 after each commit lands). Both hooks follow the existing bash-wrapper-delegates-to-Python pattern. Update `CONTRIBUTING.md` to document the new check and bypass.

---

## Implementation Steps

### 1. Create `scripts/check_pr_size.py`

This is the core logic module. It must:

- Accept a `--staged` flag (used by pre-commit to include staged files in the cumulative count).
- Resolve the merge-base against `main` then `origin/main` as fallback (mirror the logic in `.githooks/pre-push` lines 150–161).
- Collect files changed since merge-base via `git diff --name-only <merge-base>..HEAD`.
- When `--staged` is passed, additionally collect staged files via `git diff --cached --name-only --diff-filter=ACMRD` and union them with the committed set.
- Deduplicate the combined file list.
- Check the `ALLOW_LARGE_PR` environment variable; if set to `"1"`, skip the block and print a bypass notice.
- Print a status line: `PR size: X files (warn ≥10, block ≥50)`.
- **< 10 files**: print a green pass line, exit 0.
- **10–19 files**: print a yellow `WARNING` with "Consider reviewing scope. Suggest splitting if unrelated changes are bundled.", exit 0 (non-blocking).
- **20–49 files**: print a yellow `WARNING` with "Strong warning: PR is large. Strongly suggest splitting or committing current work to a separate branch.", exit 0 (non-blocking).
- **≥ 50 files**: print a red `ERROR` with remediation guidance (see below), exit 1 (blocking).

Remediation guidance for the ≥50 block:
```
PR size: 52 files — exceeds hard limit of 50.
Split this PR or use ALLOW_LARGE_PR=1 to bypass (mass refactor only).
  git stash                          # stash uncommitted work
  gh pr create                       # open PR with current commits
  git stash pop && git checkout -b feat/part-2
```

Use `subprocess.run` with `check=False` for all git calls (consistent with `.claude/hooks/pre_commit_slash_commands.py`). Use `pathlib.Path` and standard library only — no new dependencies.

Exit codes:
| Exit | Meaning |
|------|---------|
| 0 | OK or warning (non-blocking) |
| 1 | Hard block (≥50 files) |
| 2 | Configuration error (no git, no merge-base) |

---

### 2. Modify `.githooks/pre-commit` — add PR size hard-block section

Insert a new section after the existing branch validation block (around line 103) and before the staged-file linting checks. Follow the existing `if/else` pattern used for ruff and actionlint checks (lines 280–300):

- Use `set_python_cmd` (already defined in the hook at line 160) to locate Python.
- Resolve the script path relative to `REPO_ROOT`.
- Call `scripts/check_pr_size.py --staged`.
- Capture the exit code with an `if !` guard (compatible with `set -e`).
- On exit code 1: call `record_fail` equivalent (set `EXIT_STATUS=1`) and print the remediation block.
- On exit code 0: the script already printed any warnings; no additional action needed.
- Skip gracefully if Python is unavailable (`record_skip`).

The section header should read `# PR Scope Explosion Guard (Issue #944)` for traceability.

---

### 3. Create `.githooks/post-commit`

New file, executable (`chmod +x`). Follow the same bash header pattern as `.githooks/pre-push` (color helpers, `REPO_ROOT` detection, `set_python_cmd`). Key differences from pre-commit:

- **No `set -e`** — post-commit must never block (git ignores non-zero exit from post-commit, but it's confusing to users).
- Call `scripts/check_pr_size.py` (without `--staged` — the commit is already made).
- Always exit 0 regardless of script output.
- Include the same ADR-005 bash-exception comment as the other hooks.

The header comment should note: _"post-commit: informational only. Displays cumulative PR size after each commit. Hard block is enforced by pre-commit."_

---

### 4. Update `CONTRIBUTING.md`

In the **Pre-Commit Hooks** section (around line 389), add a bullet:

> - **PR scope explosion guard**: Tracks cumulative files changed since branch diverged from `main`. Warns at 10 and 20 files; blocks commit at 50 files. Bypass for justified large changes: `ALLOW_LARGE_PR=1 git commit`.

In the **Pre-Push Hooks** table, note that the file-count gate also runs at push time (already documented) and that the commit-level gate provides earlier feedback.

Add a new subsection **PR Size Thresholds** (parallel to the existing **Commit Count Thresholds** section at line 585):

| File Count | Action |
|------------|--------|
| < 10 | ✅ Pass |
| 10–19 | ⚠️ Warning (review scope) |
| 20–49 | ⚠️ Strong warning (consider splitting) |
| ≥ 50 | ❌ Blocked (`ALLOW_LARGE_PR=1` to bypass) |

---

### 5. Flow diagram

```mermaid
sequenceDiagram
    participant Dev as Developer
    participant PreCommit as .githooks/pre-commit
    participant Script as scripts/check_pr_size.py
    participant PostCommit as .githooks/post-commit

    Dev->>PreCommit: git commit
    PreCommit->>Script: python check_pr_size.py --staged
    Script->>Script: merge-base(HEAD, main/origin/main)
    Script->>Script: committed_files = diff(merge-base..HEAD)
    Script->>Script: staged_files = git diff --cached
    Script->>Script: total = union(committed, staged)
    alt total < 10
        Script-->>PreCommit: exit 0 (pass)
    else 10 ≤ total < 50
        Script-->>PreCommit: exit 0 + WARNING printed
    else total ≥ 50 and ALLOW_LARGE_PR≠1
        Script-->>PreCommit: exit 1 (block)
        PreCommit-->>Dev: ❌ Commit blocked — split PR or set ALLOW_LARGE_PR=1
    end
    PreCommit-->>Dev: Commit succeeds
    Dev->>PostCommit: (auto-triggered after commit)
    PostCommit->>Script: python check_pr_size.py
    Script-->>PostCommit: PR size: X files
    PostCommit-->>Dev: Informational display (always exit 0)
```

---

Execution Information

Branch: main
Commit: 94e7a50