forgejo_admin/pal-e-platform

Fork 1

Python repo standards: ruff pre-commit hooks + repo setup template #29

New issue

Open

opened 2026-03-09 22:34:35 +00:00 by forgejo_admin · 4 comments

forgejo_admin commented

2026-03-09 22:34:35 +00:00

Owner

Type

Feature

Lineage

Board: board-pal-e-platform
Story: story:superuser-deploy
Arch: arch:ci-pipeline, arch:developer-tooling

Repo

forgejo_admin/pal-e-platform (tracking issue — child work spans 6 repos + claude-custom)

User Story

As a platform operator, I want all Python repos to enforce code formatting before CI so that CI never fails on formatting and agents produce clean code from the start.

Context

Multiple Python repos fail CI on ruff format --check because there are no pre-commit hooks. Devs and agents push unformatted code, CI catches it too late. With Woodpecker logs currently broken, these failures are invisible. This is whack-a-mole without a platform standard.

Scope decisions (resolved 2026-03-28):

Line-length: 88 (ruff/Black default, zero config)
Lint rules: E,F,I,W (exclude N naming rules — standardize on essentials)
Archive candidates excluded: mcd-tracker-api, mcd-tracker-app, pal-e-mail are deprecated. Not in scope.
Claude hooks already partially close the gap: auto-ruff-format.sh and check-ruff-before-commit.sh exist in claude-custom. This ticket standardizes the repo-side config they depend on.

Repos in scope (6)

Repo	Local path	Notes
pal-e-api	~/pal-e-docs	Backend API
basketball-api	~/basketball-api	Sports API
minio-sdk	~/minio-sdk	S3 SDK
minio-api	~/minio-api	S3 REST service
pal-e-mcp	~/pal-e-mcp	MCP server
gmail-mcp	TBD	Gmail OAuth MCP

Decomposition (4 workstreams)

Per review-55-2026-03-28, this umbrella decomposes into:

Convention note — document the ruff standard (line-length=88, select=E,F,I,W, pyproject.toml section). Dottie task.
Per-repo remediation — apply standard pyproject.toml ruff config + .pre-commit-config.yaml to each repo. 6 Dev agents (one per repo).
CI standardization — ensure each repo's .woodpecker.yaml has ruff check + ruff format --check steps. Can be batched with remediation.
SOP update — add ruff to service-onboarding-sop and PR conventions. Dottie task.

File Targets (per repo)

pyproject.toml — ruff config section (line-length=88, select=["E","F","I","W"])
.pre-commit-config.yaml — ruff pre-commit hook
.woodpecker.yaml — ruff check step in CI (if not already present)

Acceptance Criteria

Standard ruff config defined and documented in convention note
All 6 repos have matching pyproject.toml ruff config
All 6 repos have .pre-commit-config.yaml with ruff hook
CI pipelines include ruff check step
service-onboarding-sop updated with ruff requirement

Test Expectations

Per repo: ruff check . passes clean
Per repo: ruff format --check . passes clean
Per repo: pre-commit run --all-files passes

Constraints

One PR per repo (per feedback_smaller_scopes_parallel)
Archive candidates (mcd-tracker-*, pal-e-mail) explicitly excluded
Existing claude-custom hooks (auto-ruff-format.sh, check-ruff-before-commit.sh) are complementary — don't duplicate

Checklist

Create convention note
Create per-repo sub-issues
Dispatch agents
Update SOP

forgejo_admin/claude-custom — existing ruff hooks
service-onboarding-sop — needs ruff section
review-55-2026-03-28 — scope review with 8-repo audit

### Type Feature ### Lineage - Board: board-pal-e-platform - Story: story:superuser-deploy - Arch: arch:ci-pipeline, arch:developer-tooling ### Repo `forgejo_admin/pal-e-platform` (tracking issue — child work spans 6 repos + claude-custom) ### User Story As a platform operator, I want all Python repos to enforce code formatting before CI so that CI never fails on formatting and agents produce clean code from the start. ### Context Multiple Python repos fail CI on `ruff format --check` because there are no pre-commit hooks. Devs and agents push unformatted code, CI catches it too late. With Woodpecker logs currently broken, these failures are invisible. This is whack-a-mole without a platform standard. **Scope decisions (resolved 2026-03-28):** - **Line-length: 88** (ruff/Black default, zero config) - **Lint rules: E,F,I,W** (exclude N naming rules — standardize on essentials) - **Archive candidates excluded:** mcd-tracker-api, mcd-tracker-app, pal-e-mail are deprecated. Not in scope. - **Claude hooks already partially close the gap:** `auto-ruff-format.sh` and `check-ruff-before-commit.sh` exist in claude-custom. This ticket standardizes the repo-side config they depend on. ### Repos in scope (6) | Repo | Local path | Notes | |------|-----------|-------| | pal-e-api | ~/pal-e-docs | Backend API | | basketball-api | ~/basketball-api | Sports API | | minio-sdk | ~/minio-sdk | S3 SDK | | minio-api | ~/minio-api | S3 REST service | | pal-e-mcp | ~/pal-e-mcp | MCP server | | gmail-mcp | TBD | Gmail OAuth MCP | ### Decomposition (4 workstreams) Per review-55-2026-03-28, this umbrella decomposes into: 1. **Convention note** — document the ruff standard (line-length=88, select=E,F,I,W, pyproject.toml section). Dottie task. 2. **Per-repo remediation** — apply standard pyproject.toml ruff config + .pre-commit-config.yaml to each repo. 6 Dev agents (one per repo). 3. **CI standardization** — ensure each repo's .woodpecker.yaml has `ruff check` + `ruff format --check` steps. Can be batched with remediation. 4. **SOP update** — add ruff to service-onboarding-sop and PR conventions. Dottie task. ### File Targets (per repo) - `pyproject.toml` — ruff config section (line-length=88, select=["E","F","I","W"]) - `.pre-commit-config.yaml` — ruff pre-commit hook - `.woodpecker.yaml` — ruff check step in CI (if not already present) ### Acceptance Criteria - [ ] Standard ruff config defined and documented in convention note - [ ] All 6 repos have matching pyproject.toml ruff config - [ ] All 6 repos have .pre-commit-config.yaml with ruff hook - [ ] CI pipelines include ruff check step - [ ] service-onboarding-sop updated with ruff requirement ### Test Expectations - [ ] Per repo: `ruff check .` passes clean - [ ] Per repo: `ruff format --check .` passes clean - [ ] Per repo: `pre-commit run --all-files` passes ### Constraints - One PR per repo (per feedback_smaller_scopes_parallel) - Archive candidates (mcd-tracker-*, pal-e-mail) explicitly excluded - Existing claude-custom hooks (auto-ruff-format.sh, check-ruff-before-commit.sh) are complementary — don't duplicate ### Checklist - [ ] Create convention note - [ ] Create per-repo sub-issues - [ ] Dispatch agents - [ ] Update SOP ### Related - `forgejo_admin/claude-custom` — existing ruff hooks - `service-onboarding-sop` — needs ruff section - `review-55-2026-03-28` — scope review with 8-repo audit

forgejo_admin commented

2026-03-27 21:33:31 +00:00

Author

Owner

Scope Review: NEEDS_REFINEMENT

Review note: review-55-2026-03-27

Ticket is well-structured but too large for a single agent pass and missing traceability labels. Key findings:

Missing traceability: no story:X or arch:X labels on board item #55
Missing ### Type header in issue body
Repo audit list incomplete: issue lists 5 repos but 8 Python repos exist (missing minio-api, pal-e-mail, mcd-tracker-api). "dora-exporter" should be "pal-e-dora-exporter"
Config divergence discovered: line-length splits 100 vs 120 across repos; lint rules differ (some include "N" naming checks, some don't). Standardizing will cause mass reformatting
Claude hooks already exist: auto-ruff-format.sh and check-ruff-before-commit.sh are already registered — issue scope needs updating
AC #5 ambiguous: "CI pipeline patterns standardized" — 5 of 8 repos have no .woodpecker.yml at all
Needs decomposition: 8 repos, 3+ files each, multiple phases. Issue already self-identifies as plan-level

Recommend decomposition via template-board before moving to next_up.

## Scope Review: NEEDS_REFINEMENT Review note: `review-55-2026-03-27` Ticket is well-structured but too large for a single agent pass and missing traceability labels. Key findings: - **Missing traceability**: no `story:X` or `arch:X` labels on board item #55 - **Missing `### Type` header** in issue body - **Repo audit list incomplete**: issue lists 5 repos but 8 Python repos exist (missing minio-api, pal-e-mail, mcd-tracker-api). "dora-exporter" should be "pal-e-dora-exporter" - **Config divergence discovered**: line-length splits 100 vs 120 across repos; lint rules differ (some include "N" naming checks, some don't). Standardizing will cause mass reformatting - **Claude hooks already exist**: `auto-ruff-format.sh` and `check-ruff-before-commit.sh` are already registered — issue scope needs updating - **AC #5 ambiguous**: "CI pipeline patterns standardized" — 5 of 8 repos have no .woodpecker.yml at all - **Needs decomposition**: 8 repos, 3+ files each, multiple phases. Issue already self-identifies as plan-level Recommend decomposition via `template-board` before moving to next_up.

forgejo_admin commented

2026-03-28 05:43:30 +00:00

Author

Owner

Scope Review: NEEDS_REFINEMENT

Review note: review-55-2026-03-27

Ticket is well-structured but too large for a single agent pass and missing traceability labels. Key findings:

Traceability gaps: Missing story:X and arch:X labels on board item #55
File targets unscoped: "Needs scoping" confirmed -- audit found 7 repos lacking .pre-commit-config.yaml (only pal-e-docs has it). All 7 have [tool.ruff] in pyproject.toml already.
Partial solution exists: claude-custom/hooks/check-ruff-before-commit.sh and auto-ruff-format.sh already enforce ruff at agent commit time
Audit list incomplete: minio-api, pal-e-mail, mcd-tracker-api missing from issue. "dora-exporter" should be "pal-e-dora-exporter"
AC #5 ambiguous: "CI pipeline patterns standardized" -- unclear whether this means .woodpecker.yml ruff steps or claude-custom hooks (which already exist)
Archive candidates in scope: mcd-tracker-api and pal-e-mail may be wasted remediation effort

Recommend decomposition via template-board into: (1) convention note, (2) SOP update, (3) per-repo remediation tickets, (4) CI standardization.

## Scope Review: NEEDS_REFINEMENT Review note: `review-55-2026-03-27` Ticket is well-structured but too large for a single agent pass and missing traceability labels. Key findings: - **Traceability gaps:** Missing `story:X` and `arch:X` labels on board item #55 - **File targets unscoped:** "Needs scoping" confirmed -- audit found 7 repos lacking `.pre-commit-config.yaml` (only pal-e-docs has it). All 7 have `[tool.ruff]` in pyproject.toml already. - **Partial solution exists:** `claude-custom/hooks/check-ruff-before-commit.sh` and `auto-ruff-format.sh` already enforce ruff at agent commit time - **Audit list incomplete:** minio-api, pal-e-mail, mcd-tracker-api missing from issue. "dora-exporter" should be "pal-e-dora-exporter" - **AC #5 ambiguous:** "CI pipeline patterns standardized" -- unclear whether this means .woodpecker.yml ruff steps or claude-custom hooks (which already exist) - **Archive candidates in scope:** mcd-tracker-api and pal-e-mail may be wasted remediation effort Recommend decomposition via template-board into: (1) convention note, (2) SOP update, (3) per-repo remediation tickets, (4) CI standardization.

forgejo_admin commented

2026-03-28 18:40:07 +00:00

Author

Owner

Scope Review: NEEDS_REFINEMENT

Review note: review-55-2026-03-28

Third review — issue body unchanged since prior two reviews (2026-03-27). All prior findings confirmed against current codebase. Key issues:

Traceability gaps: Missing story:X and arch:X labels on board item #55
File targets still unscoped: "Needs scoping" remains. Audit confirms 8 Python repos — all have [tool.ruff] in pyproject.toml, only pal-e-docs has .pre-commit-config.yaml, only 3/8 have .woodpecker.yml with ruff steps
Config divergence requires human decision: line-length split (100 vs 120, 3 repos vs 5), lint rules split ("N" naming in 3 repos, absent in 5). Standardizing will cause mass reformatting
Claude hooks already exist: auto-ruff-format.sh and check-ruff-before-commit.sh already enforce ruff at agent commit time — issue scope needs updating
Audit list incomplete: minio-api, pal-e-mail, mcd-tracker-api, pal-e-mcp missing. "dora-exporter" should be "pal-e-dora-exporter"
AC #5 ambiguous: "CI pipeline patterns standardized" — 5 of 8 repos have no .woodpecker.yml at all
Archive candidates in scope: mcd-tracker-api and pal-e-mail may be wasted remediation effort
Needs decomposition: 8 repos, 2-3 files each, 5 AC — well beyond 5-minute rule. Recommend template-board decomposition into: (1) convention note, (2) SOP update, (3) per-repo remediation tickets, (4) CI standardization

3 [SCOPE] decisions needed from Lucas before refinement can proceed.

## Scope Review: NEEDS_REFINEMENT Review note: `review-55-2026-03-28` Third review — issue body unchanged since prior two reviews (2026-03-27). All prior findings confirmed against current codebase. Key issues: - **Traceability gaps:** Missing `story:X` and `arch:X` labels on board item #55 - **File targets still unscoped:** "Needs scoping" remains. Audit confirms 8 Python repos — all have `[tool.ruff]` in pyproject.toml, only pal-e-docs has `.pre-commit-config.yaml`, only 3/8 have `.woodpecker.yml` with ruff steps - **Config divergence requires human decision:** line-length split (100 vs 120, 3 repos vs 5), lint rules split ("N" naming in 3 repos, absent in 5). Standardizing will cause mass reformatting - **Claude hooks already exist:** `auto-ruff-format.sh` and `check-ruff-before-commit.sh` already enforce ruff at agent commit time — issue scope needs updating - **Audit list incomplete:** minio-api, pal-e-mail, mcd-tracker-api, pal-e-mcp missing. "dora-exporter" should be "pal-e-dora-exporter" - **AC #5 ambiguous:** "CI pipeline patterns standardized" — 5 of 8 repos have no .woodpecker.yml at all - **Archive candidates in scope:** mcd-tracker-api and pal-e-mail may be wasted remediation effort - **Needs decomposition:** 8 repos, 2-3 files each, 5 AC — well beyond 5-minute rule. Recommend template-board decomposition into: (1) convention note, (2) SOP update, (3) per-repo remediation tickets, (4) CI standardization 3 `[SCOPE]` decisions needed from Lucas before refinement can proceed.

forgejo_admin commented

2026-03-28 18:49:28 +00:00

Author

Owner

Scope Review: READY

Review note: review-55-2026-03-28-r4

Fourth review (re-review after major body rewrite). All 3 prior NEEDS_REFINEMENT findings resolved: scope decisions locked (line-length=88, E/F/I/W, archives excluded), traceability labels added, 4-workstream decomposition defined, 6-repo scope table with file targets included.

Key finding: All 6 repos already have CI ruff steps — workstream 3 (CI standardization) is a no-op. Remaining work is config alignment (line-length → 88) + adding .pre-commit-config.yaml to 5 repos.

Non-blocking nits:

pal-e-sdk (~/pal-e-docs-sdk) missing from scope — active Python repo, not archive candidate
AC #4 and workstream 3 are pre-satisfied (CI ruff already present everywhere)
gmail-mcp uses target-version py310 vs py312 standard — convention note should address

## Scope Review: READY Review note: `review-55-2026-03-28-r4` Fourth review (re-review after major body rewrite). All 3 prior NEEDS_REFINEMENT findings resolved: scope decisions locked (line-length=88, E/F/I/W, archives excluded), traceability labels added, 4-workstream decomposition defined, 6-repo scope table with file targets included. **Key finding:** All 6 repos already have CI ruff steps — workstream 3 (CI standardization) is a no-op. Remaining work is config alignment (line-length → 88) + adding .pre-commit-config.yaml to 5 repos. **Non-blocking nits:** - pal-e-sdk (~/pal-e-docs-sdk) missing from scope — active Python repo, not archive candidate - AC #4 and workstream 3 are pre-satisfied (CI ruff already present everywhere) - gmail-mcp uses target-version py310 vs py312 standard — convention note should address