Add pre-commit ruff enforcement hook for all Python repos

forgejo_admin commented

2026-03-13 19:16:16 +00:00

Contributor

Lineage

pal-e-agency — standalone improvement (no plan phase — platform-wide dev tooling)

Repo

forgejo_admin/claude-custom

User Story

As a platform operator
I want ruff lint violations to be caught before any git commit in any Python repo
So that CI never breaks due to formatting/lint issues again

Context

basketball-api CI was broken for multiple pipelines (#59) because ruff violations were committed without being caught. The fix was trivial (6 violations in 2 files) but required manual intervention and a PR cycle. This has happened repeatedly — basketball-api's git history shows 5 separate ruff fix commits.

The platform has 8 Python repos, all with ruff check + ruff format --check in Woodpecker CI. But CI catches violations too late (after push). A Claude Code PreToolUse hook can catch them before commit.

pal-e-docs already has .pre-commit-config.yaml — the other 7 repos don't.

File Targets

Files to create:

hooks/check-ruff-before-commit.sh — PreToolUse hook, fires on Bash tool use containing git commit, runs ruff check . if Python repo (pyproject.toml exists), blocks if violations found

Files to modify:

settings.json — wire hook into Bash PreToolUse matchers

Files NOT to touch:

Per-repo .pre-commit-config.yaml — separate issue, not this scope
Existing hooks — no modifications needed

Acceptance Criteria

git commit in a Python repo with ruff violations is blocked with helpful error
git commit in a Python repo with clean ruff passes through
git commit in a non-Python repo (no pyproject.toml) passes through
Hook fails open (if ruff binary missing or other error, allow the commit)
Hook matches existing pattern (check-agent-spawn.sh, block-main-commits.sh)

Test Expectations

Manual test: introduce a ruff violation, attempt commit, verify blocked
Manual test: fix violation, attempt commit, verify passes
Manual test: commit in pal-e-platform (non-Python), verify passes

Constraints

Follow existing hook patterns in hooks/ directory
Fail-open on errors (trap 'exit 0' ERR)
Must work in agent worktrees (not just main checkout)
Hook deploys via hardlink — git pull on claude-custom auto-deploys

Checklist

PR opened
Tests pass
No unrelated changes

basketball-api #59 — the incident that motivated this
pal-e-agency — project this belongs to

### Lineage `pal-e-agency` — standalone improvement (no plan phase — platform-wide dev tooling) ### Repo `forgejo_admin/claude-custom` ### User Story As a platform operator I want ruff lint violations to be caught before any git commit in any Python repo So that CI never breaks due to formatting/lint issues again ### Context basketball-api CI was broken for multiple pipelines (#59) because ruff violations were committed without being caught. The fix was trivial (6 violations in 2 files) but required manual intervention and a PR cycle. This has happened repeatedly — basketball-api's git history shows 5 separate ruff fix commits. The platform has 8 Python repos, all with `ruff check` + `ruff format --check` in Woodpecker CI. But CI catches violations too late (after push). A Claude Code PreToolUse hook can catch them before commit. pal-e-docs already has `.pre-commit-config.yaml` — the other 7 repos don't. ### File Targets Files to create: - `hooks/check-ruff-before-commit.sh` — PreToolUse hook, fires on Bash tool use containing `git commit`, runs `ruff check .` if Python repo (pyproject.toml exists), blocks if violations found Files to modify: - `settings.json` — wire hook into Bash PreToolUse matchers Files NOT to touch: - Per-repo `.pre-commit-config.yaml` — separate issue, not this scope - Existing hooks — no modifications needed ### Acceptance Criteria - [ ] `git commit` in a Python repo with ruff violations is blocked with helpful error - [ ] `git commit` in a Python repo with clean ruff passes through - [ ] `git commit` in a non-Python repo (no pyproject.toml) passes through - [ ] Hook fails open (if ruff binary missing or other error, allow the commit) - [ ] Hook matches existing pattern (check-agent-spawn.sh, block-main-commits.sh) ### Test Expectations - [ ] Manual test: introduce a ruff violation, attempt commit, verify blocked - [ ] Manual test: fix violation, attempt commit, verify passes - [ ] Manual test: commit in pal-e-platform (non-Python), verify passes ### Constraints - Follow existing hook patterns in `hooks/` directory - Fail-open on errors (trap 'exit 0' ERR) - Must work in agent worktrees (not just main checkout) - Hook deploys via hardlink — `git pull` on claude-custom auto-deploys ### Checklist - [ ] PR opened - [ ] Tests pass - [ ] No unrelated changes ### Related - `basketball-api #59` — the incident that motivated this - `pal-e-agency` — project this belongs to