# Git Hooks Documentation

## PR Monitoring Reminder (pre-push hook)

This repository includes a git pre-push hook that automatically reminds developers to monitor PRs for feedback after pushing commits.

### Features

- **Automatic PR Detection**: Detects if the current branch has an open PR
- **Monitoring Instructions**: Provides exact commands to monitor PR feedback
- **Works Everywhere**: Functions with all git push operations (CLI, Claude Code, AI agents, etc.)
- **Git LFS Compatible**: Preserves existing Git LFS functionality

### What It Does

When you run `git push`, the hook will:

1. Check if your branch has an open PR
2. Display monitoring instructions with the correct PR number and commit SHA
3. Remind you about the types of feedback to watch for (admin comments, AI agent reviews, CI/CD)

### Example Output

```
============================================================
PR FEEDBACK MONITORING REMINDER
============================================================

You're pushing commits to PR #54 on branch 'refine'.
After push completes, consider monitoring for feedback:

  Monitor from this commit onwards:
     pr-monitor 54 --since-commit abc1234

  Or monitor all new comments:
     pr-monitor 54

This will watch for:
  - Admin comments and commands
  - AI agent code review feedback
  - CI/CD validation results

The monitor will return structured data when relevant comments are detected.
============================================================
```

### Dependencies

For optimal functionality, install these tools:

```bash
# GitHub CLI (required for PR detection)
# Ubuntu/Debian:
sudo apt install gh
# Or download from: https://cli.github.com/

# jq (recommended for robust JSON parsing)
# Ubuntu/Debian:
sudo apt install jq
# macOS:
brew install jq
```

### Installation

#### Automatic Installation

To install the pre-push hook in your local repository:

```bash
# Copy the pre-push hook to your git hooks directory
cp scripts/git-hooks/pre-push .git/hooks/pre-push
chmod +x .git/hooks/pre-push
```

#### Manual Installation

If you prefer to install manually or need to combine with existing hooks:

1. Create or edit `.git/hooks/pre-push`
2. Add the monitoring reminder functionality (see `scripts/git-hooks/pre-push` for reference)
3. Make the hook executable: `chmod +x .git/hooks/pre-push`

#### Important Notes

- This is a local git hook that is NOT tracked in the repository (stays local to your clone)
- If you have Git LFS installed, the hook will automatically combine with LFS functionality
- Requires `gh` CLI to be installed for PR detection to work
- Recommends `jq` for robust JSON parsing (falls back to grep if not available)

### Customization

To modify or disable the hook, edit `.git/hooks/pre-push` in your local repository.

### Related Tools

- **PR Monitor**: `tools/rust/pr-monitor/` (Rust binary for PR comment monitoring)
- **gh-validator**: See `tools/rust/gh-validator/README.md`
- **GitHub AI Agents**: Automated PR and issue monitoring

## Security Validation (gh-validator)

The repository includes a Rust-based security validator that works with ALL agents through PATH shadowing:

- **gh-validator binary**: `~/.local/bin/gh`
  - Masks secrets in GitHub comments
  - Blocks Unicode emojis
  - Validates reaction image URLs (SSRF protection)
  - Blocks stdin usage for security
  - Works for all agents including Claude Code
  - See `docs/developer/claude-code-hooks.md` for details

This validator ensures that sensitive information is never accidentally posted to GitHub through any automation tool or manual operation.
