pal-e-docs

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

review-55-2026-03-27 Review

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

  • [x] Lineage -- "New plan needed -- Python Repo Standards"
  • [x] Repo -- pal-e-platform (convention), claude-custom (hooks/skills)
  • [x] User Story -- "As a platform operator I want all Python repos to enforce code formatting before CI..."
  • [x] Context -- explains whack-a-mole CI failures from missing pre-commit hooks
  • [ ] File Targets -- says "Needs scoping" with bullet-point categories only, no specific file paths
  • [x] Acceptance Criteria -- 5 items present
  • [x] Test Expectations -- present with run command
  • [x] Constraints -- "Needs a proper plan" + audit list
  • [x] Checklist -- present
  • [x] Related -- service-onboarding-sop, basketball-api #15
  • [ ] Type header -- missing (acceptable, falls back to Feature)

Traceability

  • [ ] story:X label -- MISSING. No user story label on board item. The issue body contains a user story ("As a platform operator...") but the board item label is absent. Foundational/tooling work -- borderline acceptable but should have a story label for traceability (e.g. story:platform-standards).
  • [ ] arch:X label -- MISSING. No architecture component label. This work touches CI pipeline config and developer tooling. Recommend arch:ci-pipeline.
  • [x] Forgejo issue -- forgejo_admin/pal-e-platform#29, open

File Targets

Issue says "Needs scoping." Codebase audit reveals the actual landscape:
  • [x] pal-e-docs -- HAS .pre-commit-config.yaml (ruff v0.15.2) + [tool.ruff] in pyproject.toml. This is the template to replicate.
  • [ ] pal-e-docs-sdk -- HAS [tool.ruff] in pyproject.toml, NO .pre-commit-config.yaml
  • [ ] basketball-api -- HAS [tool.ruff] in pyproject.toml, NO .pre-commit-config.yaml
  • [ ] minio-sdk -- HAS [tool.ruff] in pyproject.toml, NO .pre-commit-config.yaml
  • [ ] minio-api -- HAS [tool.ruff] in pyproject.toml, NO .pre-commit-config.yaml
  • [ ] pal-e-mail -- HAS [tool.ruff] in pyproject.toml, NO .pre-commit-config.yaml
  • [ ] mcd-tracker-api -- HAS [tool.ruff] in pyproject.toml, NO .pre-commit-config.yaml
  • [ ] pal-e-dora-exporter -- exists on Forgejo as forgejo_admin/pal-e-dora-exporter, not cloned locally, status unknown
  • [x] claude-custom/hooks/check-ruff-before-commit.sh -- EXISTS, blocks git commit on ruff violations
  • [x] claude-custom/hooks/auto-ruff-format.sh -- EXISTS, auto-formats staged .py files before commit
Key finding: claude-custom hooks already enforce ruff format + lint at agent commit time. The remaining gap is .pre-commit-config.yaml in 6-7 repos (for human developers and non-Claude CI environments).
Repo name discrepancy: Issue references "dora-exporter" but the Forgejo repo is forgejo_admin/pal-e-dora-exporter.
Missing from audit list in issue: minio-api, pal-e-mail, mcd-tracker-api are not listed as audit targets but all have pyproject.toml with [tool.ruff] and no .pre-commit-config.yaml.

Repo Placement

Issue filed on pal-e-platform (convention/governance home) -- correct for a standards issue. However, actual remediation touches 8+ Python repos. Each repo remediation needs its own Forgejo issue on its own repo. This is correctly identified in the issue's Constraints section ("Needs a proper plan").

Dependencies

  • No blocking items found on board-pal-e-platform. Board item #55 is in todo column.
  • basketball-api #15 referenced as "immediate ruff fix" -- appears to be a standalone remediation already tracked. basketball-api still lacks .pre-commit-config.yaml.
  • service-onboarding-sop needs updating to include ruff/pre-commit as a standard step -- not currently in the SOP's pre-deploy checklist or scaffold section.
  • No upstream blockers. This is a standards/tooling initiative that can proceed independently.

Acceptance Criteria

5 AC items. Assessment:
  • "Standard ruff config defined" -- verifiable but vague. Which ruff rules? What line-length? pal-e-docs has an existing [tool.ruff] config that could be the template, but the AC doesn't specify the canonical source.
  • "Pre-commit hook config templated" -- verifiable. pal-e-docs/.pre-commit-config.yaml is the existing template (ruff-format + ruff check).
  • "New Python repos get hooks + config from repo setup" -- requires SOP update to service-onboarding-sop or a new convention note. Not verifiable without specifying where the template lives and how it gets applied.
  • "All existing Python repos remediated" -- verifiable via ruff format --check . && ruff check . per repo. But this is 7+ repos, each needing its own PR.
  • "CI pipeline patterns standardized" -- AMBIGUOUS. Does this mean a ruff step in .woodpecker.yaml? The claude-custom hooks already handle agent-side enforcement. Several repos lack .woodpecker.yml entirely.

Blast Radius

  • 7+ Python repos need .pre-commit-config.yaml added.
  • Some repos may have formatting drift that needs remediation before the check passes (ruff format --check may fail on existing code, causing mass reformatting diffs).
  • claude-custom hooks (check-ruff-before-commit.sh, auto-ruff-format.sh) already exist and partially address the agent enforcement gap -- this should be acknowledged in scope.
  • service-onboarding-sop needs a new step for ruff/pre-commit in the scaffold section.
  • No downstream consumers affected -- this is additive tooling.
  • mcd-tracker-api and pal-e-mail are archive candidates per feedback_archive_mcd_palemail -- including them in remediation may be wasted work.

Decomposition

NEEDS DECOMPOSITION. Assessment:
  • [x] >3 file targets across >2 repos -- YES (8+ repos, multiple files each)
  • [x] 5 acceptance criteria -- at the threshold
  • [x] Estimated agent work >5 minutes -- YES, significantly. Each repo remediation is its own PR with potential formatting drift to fix.
  • The issue itself says "Needs a proper plan in pal-e-docs before work starts" -- it was written as a plan-level tracking issue, not an agent-dispatchable ticket.
Recommend decomposition via template-board into at minimum:
  • Convention note: define standard ruff config + .pre-commit-config.yaml template (use pal-e-docs as reference)
  • SOP update: add ruff/pre-commit to service-onboarding-sop scaffold step
  • Per-repo remediation tickets (one per repo, 5-7 tickets): add .pre-commit-config.yaml, verify ruff passes
  • CI standardization: add ruff check steps to .woodpecker.yml for repos that have CI pipelines

Recommendation

  • [LABEL] Add arch:ci-pipeline label to board item #55
  • [LABEL] Add story:platform-standards label (or similar) to board item #55 for traceability
  • [BODY] Add ### Type header with value Feature
  • [BODY] Replace "Needs scoping" file targets with the audit results from this review (7 repos lacking .pre-commit-config.yaml, 2 claude-custom hooks already exist)
  • [BODY] Fix repo name: "dora-exporter" should be "pal-e-dora-exporter"
  • [BODY] Add missing repos to audit list: minio-api, pal-e-mail, mcd-tracker-api
  • [BODY] Clarify AC #5 "CI pipeline patterns standardized" -- does this mean a ruff step in .woodpecker.yaml, or are the claude-custom hooks sufficient?
  • [BODY] Acknowledge existing claude-custom hooks (check-ruff-before-commit.sh, auto-ruff-format.sh) -- agent-side enforcement is already in place
  • [SCOPE] Clarify: are mcd-tracker-api and pal-e-mail still in scope given they are archive candidates (feedback_archive_mcd_palemail)?
  • [DECOMPOSE] 8+ repos, 5 AC, well beyond 5-minute rule. Split into sub-board via template-board: (1) convention note, (2) SOP update, (3) per-repo remediation tickets, (4) CI standardization.