---
name: audit-pre-commit
description: Audit a repository's pre-commit hook configuration for security and code quality compliance. Checks that gitleaks (mandatory) and ruff (recommended) hooks are configured, and that all hook rev values are pinned. Use when auditing a repo for missing or misconfigured pre-commit hooks, or as part of a full security audit via generate-security-report.
argument-hint: "[path-to-repo-root]"
---

# Audit Pre-Commit Hooks

Scan `.pre-commit-config.yaml` and apply the checklist at
`${CLAUDE_SKILL_DIR}/references/checklist.md`.

**Argument**: `$ARGUMENTS`

---

## Step 1 — Locate .pre-commit-config.yaml

If `$ARGUMENTS` is provided, use it as the repo root. Otherwise use the current
working directory.

Look for `.pre-commit-config.yaml` at the repo root using the Glob tool:
`<repo-root>/.pre-commit-config.yaml`

If the file is absent, emit this finding and stop:

```
## Pre-Commit Hooks Security Audit
Config file: not found

### 🔴 Critical

**[PC-1 — Config absent]** — repo root
No `.pre-commit-config.yaml` found. The repository has no pre-commit hook
configuration — secret scanning (gitleaks) and linting (ruff) are not enforced
at commit time.
Fix: Create `.pre-commit-config.yaml` at the repo root with at minimum a gitleaks
hook. See the checklist for a minimal secure baseline with both gitleaks and ruff.
```

Then output this summary table:

| Check | Status | Findings |
|---|---|---|
| .pre-commit-config.yaml present | FAIL | Config file absent |
| gitleaks configured | SKIP | No config file |
| ruff configured | SKIP | No config file |
| rev pinning | SKIP | No config file |

**STOP. The audit is complete. Do not proceed to Step 2, 3, or 4.**

---

## Step 2 — Read the config file

> Only reach this step if `.pre-commit-config.yaml` was found in Step 1.

Read `.pre-commit-config.yaml` using the Read tool.

Also read `${CLAUDE_SKILL_DIR}/references/checklist.md` in full.

---

## Step 3 — Apply the checklist

Apply each check to the config file contents.

### Check PC-2: gitleaks configured

Scan all `hooks:` blocks across all `repos:` entries. Look for a line where `id:` is followed by exactly `gitleaks` (the value must
be `gitleaks` only — not a prefix match like `gitleaks-custom`). YAML inline
comments on the same line do not affect the match.

- **PASS**: at least one `id: gitleaks` entry exists
- **FAIL** (Critical): no `id: gitleaks` found anywhere in the file

### Check PC-3: ruff configured

Scan all `hooks:` blocks. Look for a line where `id:` is followed by exactly `ruff` or exactly
`ruff-format`. A hook id that merely contains the substring `ruff` (e.g.
`ruff-extended`) does not satisfy this check.

- **PASS**: at least one `id: ruff` or `id: ruff-format` entry exists
- **FAIL** (Recommended): neither appears anywhere in the file

### Check PC-4: rev pinning

Scan all `rev:` lines across all `repos:` entries. A rev is floating if its
value matches any of: `main`, `master`, `HEAD`, `latest`, or is an empty string.
Also treat as floating any `rev:` value that does not match a semver-style
version tag (starts with `v` followed by digits, e.g. `v8.21.2`) or a full
40-character lowercase hex SHA digest — for example `rev: develop` or
`rev: stable` are floating.

For each floating rev found, record the repo URL and the floating value.

- **PASS**: all `rev:` values are specific version tags or SHA digests
- **FAIL** (Important): one or more `rev:` values are floating — list each
  affected repo URL and its current rev value

---

## Step 4 — Output findings

### Header

```
## Pre-Commit Hooks Security Audit
Config file: <path>/.pre-commit-config.yaml
Repos configured: <N>
Total hooks: <N>
```

### Findings by severity

Group findings under these headings (omit a heading if there are no findings
in that tier):

```
### 🔴 Critical
### 🟠 Important
### 🟡 Recommended
### ⚪ Note
```

Each finding entry:

```
**[PC-N — Check name]** — `.pre-commit-config.yaml`
<One-sentence description of what was found and why it is a risk.>
Fix: <concrete remediation — the key change required, with a short YAML snippet.>
```

### Summary table

| Check | Status | Findings |
|---|---|---|
| .pre-commit-config.yaml present | PASS / FAIL | — |
| gitleaks configured | PASS / FAIL / SKIP | — |
| ruff configured | PASS / FAIL / SKIP | — |
| rev pinning | PASS / FAIL / SKIP | N repos with floating revs |

### Passed checks

List all checks that passed (no findings) as a brief bullet list.

---

## Notes

- This skill is read-only. It does not modify any files.
- If `.pre-commit-config.yaml` is absent, checks PC-2 through PC-4 are skipped.
- Finding IDs use the `PC-N` prefix when aggregated in `generate-security-report`.
- Never include actual secret values in output — this skill does not read `.env`
  files or credentials.