# Design: audit-pre-commit skill

**Date**: 2026-04-16
**Plugin**: gemma-deployment-security
**Author**: Lui Pillmann

---

## Summary

Add a new read-only audit skill `audit-pre-commit` to the `gemma-deployment-security` plugin that checks whether a repository has pre-commit hooks configured correctly. Also update `generate-security-report` to auto-detect and run the skill.

---

## Scope

### In scope
- New skill: `plugins/gemma-deployment-security/skills/audit-pre-commit/`
  - `SKILL.md`
  - `references/checklist.md`
- Update: `plugins/gemma-deployment-security/skills/generate-security-report/SKILL.md`
  - Add `.pre-commit-config.yaml` detection
  - Add `PC-N` to finding ID prefix table
  - Add `audit-pre-commit` to Audit Scope table

### Out of scope
- No changes to `audit-cicd-workflows`
- No setup/fix capability — audit-only (read-only per plugin constitution)
- No checks for shellcheck, shfmt, or other hooks beyond gitleaks and ruff

---

## Checklist checks

| ID | Check | Severity | Fail condition |
|---|---|---|---|
| PC-1 | `.pre-commit-config.yaml` present at repo root | Critical | File absent |
| PC-2 | `gitleaks` hook configured | Critical | No hook with `id: gitleaks` in any repo block |
| PC-3 | `ruff` hook configured | Recommended | No hook with `id: ruff` or `id: ruff-format` in any repo block |
| PC-4 | All `rev` values pinned to specific versions | Important | Any `rev:` is `main`, `master`, `HEAD`, `latest`, or empty |

**Short-circuit rule**: if PC-1 fails (no config file), PC-2 through PC-4 are skipped — nothing to scan.

**Severity rationale:**
- PC-1 Critical: no config means no secret scanning protection at all
- PC-2 Critical: gitleaks is the user-designated mandatory hook; its absence means credentials can be committed undetected
- PC-3 Recommended: ruff is the user-designated recommended hook; absence degrades code quality but is not a security issue
- PC-4 Important: floating `rev` values (e.g., `rev: main`) expose the repo to supply-chain attacks where a compromised hook version is pulled silently — same risk profile as unpinned GitHub Actions

---

## Skill execution flow

1. Resolve the repo root path (`$ARGUMENTS` or cwd)
2. Look for `.pre-commit-config.yaml` at repo root
   - If missing: emit Critical finding PC-1, stop
3. Read and parse the YAML (as text — no YAML parser needed, use line-level pattern matching)
4. Apply checklist checks PC-2, PC-3, PC-4
5. Output findings grouped by severity, then a summary table

---

## generate-security-report changes

### Detection table addition

| Indicator | Skill |
|---|---|
| `.pre-commit-config.yaml` at repo root | `audit-pre-commit` |

### Finding ID prefix addition

| Skill | Prefix |
|---|---|
| `audit-pre-commit` | `PC-N` |

### Audit Scope table
`audit-pre-commit` appears as a row in the scope table with status (ran / skipped — reason).

---

## Constraints (from plugin constitution)

- Read-only: skill must not modify any files
- Reference-checklist architecture: checks live in `references/checklist.md`, not inline in SKILL.md
- Every check cites a source (Principle V) — source for all four checks: user specification (Gemma internal standard, 2026-04-16)
- SKILL.md must be under 500 lines
- Finding IDs are globally unique across all skills run in a single report session