feat(rules): bootstrap 3 Python doc families (pydantic, project-structure, makefile)#21
Merged
Conversation
…ture, makefile) Second Python-side bootstrap. Same multi-doc-per-PR shape as PRs #17, #18, #19. 3 docs (~467-576 lines), 6 rules. This time the RULE blocks REPLACE the existing constraint sections (not insert above), avoiding the redundancy issue that hit PR #19. Rules added (rules/index.json: 74 -> 80): python-pydantic/* (owner: python-quality-assistant) - boundary-validation-only (MUST) — Pydantic at system boundaries only (API, queue ingestion, file parser); internal domain types use dataclass / plain types to avoid validation overhead on trusted data. - optional-needs-default (MUST) — Optional[T] alone is NOT omittable; it's a type-system 'T or None'. Pair with '= None' (or Field(default=...)) when the intent is 'may be omitted'. python-project-structure/* (owner: python-architecture-assistant) - src-layout-required (MUST) — packages live in src/, not at repo root. Root layout silently picks up the dev directory via sys.path; src/ forces 'install then import' which surfaces packaging bugs. - pyproject-toml-with-hatchling (MUST) — pyproject.toml + hatchling build backend, never setup.py. PEP 517/518 declarative manifest; hatchling is the recommended PyPA backend. python-makefile/* (owner: python-quality-assistant) - precommit-target-required (MUST) — every Python project's Makefile has a precommit target running format + test + check. Project- agnostic uniform entry point for CI scripts and pre-commit hooks. - uv-not-pip-or-poetry (SHOULD) — uv for dependency management (10-100x faster than pip/poetry/pipenv, deterministic uv.lock, reads standard PEP 621 metadata). SHOULD level acknowledges legacy projects mid-migration. CLAUDE.md doc-agent table updated with all 3 new mappings. Generic examples (User, Product, iphone_backup package, etc). No personal vault paths, no trading-domain terms. make build-index regenerated; check-index passes.
![ben-s-pull-request-reviewer[bot]](https://avatars.githubusercontent.com/u/1193284?s=60&v=4){kind=small}
There was a problem hiding this comment.
I've completed my review. Let me compile the findings.
PR Review: feat(rules): bootstrap 3 Python doc families (pydantic, project-structure, makefile)
Automated Checks
- LICENSE file: Present ✓
- JSON validation: Unable to run (sandbox restrictions), but file structure appears valid
- Makefile precommit: Cannot execute (sandbox restrictions), but
check-indextarget validatesrules/index.jsonis in sync with doc RULE blocks
Manual Review Findings
rules/index.json (6 new rules added, 74→80 total):
python-makefile/precommit-target-required- MUST, owner: python-quality-assistant ✓python-makefile/uv-not-pip-or-poetry- SHOULD, owner: python-quality-assistant ✓python-project-structure/pyproject-toml-with-hatchling- MUST, owner: python-architecture-assistant ✓python-project-structure/src-layout-required- MUST, owner: python-architecture-assistant ✓python-pydantic/boundary-validation-only- MUST, owner: python-quality-assistant ✓python-pydantic/optional-needs-default- MUST, owner: python-quality-assistant ✓
All rule IDs follow correct python-<category>/<rule-name> pattern. All doc_paths correctly point to docs/*.md. All owners match CLAUDE.md alignment table.
CLAUDE.md - 3 new entries correctly added to Doc ↔ Agent table aligning with the 3 new guide additions. ✓
Duplicate content concern from PR #19: Verified that this PR correctly replaced existing constraint sections with proper ### RULE blocks rather than inserting above them — no duplicate content issue present. ✓
python-pydantic-guide.md: boundary-validation-only and optional-needs-default rules properly formatted with Bad/Good examples, proper ### RULE structure, applies_when, enforcement, Why fields. ✓
python-project-structure.md: src-layout-required and pyproject-toml-with-hatchling rules properly formatted. ✓
python-makefile-commands.md: precommit-target-required and uv-not-pip-or-poetry rules properly formatted. ✓
{
"verdict": "approve",
"summary": "PR adds 6 new Python rule blocks across 3 docs (pydantic, project-structure, makefile) with correct structure, owner alignment, and index entries. No duplicate content issues from PR #19. CLAUDE.md table correctly updated. All rule IDs, doc_paths, and owners are consistent.",
"comments": [],
"concerns_addressed": [
"correctness: rules/index.json grew 74→80 with 6 new properly structured rule entries — verified",
"correctness: docs/python-makefile-commands.md — replacement approach applied correctly, no duplicate content",
"correctness: docs/python-project-structure.md — replacement approach applied correctly, no duplicate content",
"correctness: docs/python-pydantic-guide.md — replacement approach applied correctly, no duplicate content"
]
}
bborbe
added a commit
that referenced
this pull request
Jun 2, 2026
…ncy) Third multi-doc batch shape (after PRs #17, #18, #21). 3 small Go docs (84-148 lines each), 4 rules. Bot review on one cycle. Rules added (rules/index.json: 80 -> 84): go-mod-replace/* (owner: go-quality-assistant) - no-cross-repo-replace (MUST) — replace directives must not point outside the current repo's working tree. Off-repo replaces only work on the author's machine; CI breaks; module graph becomes non-reproducible. Same-repo monorepo replaces ARE correct and remain exempt. go-glog/* (owner: go-quality-assistant) - use-v-for-debug-not-info (MUST) — V0 (bare glog.Info) is the always-on production level; debug/trace/internal-state logs use glog.V(1+). Inverting the levels produces gigabytes of noise in production and requires a deploy to change verbosity for troubleshooting. (Rule ID is all-lowercase per build-index.py regex '[a-z0-9-]+/[a-z0-9-]+' — initial attempt with capital V was rejected; walker caught it before push.) go-concurrency/* (owner: go-architecture-assistant) - no-raw-go-func (MUST) — never use 'go func()' outside main.go entry points; use github.com/bborbe/run strategies (CancelOnFirstErrorWait, All, Sequential). Raw goroutines leak, race, and require hand-rolled sync.WaitGroup that drift toward deadlocks. - channel-closed-by-sender-only (MUST) — only the producer closes a channel. Closing from the receiver side panics on still-pending sends; receivers use 'for v := range ch' or comma-ok idiom. CLAUDE.md doc-agent table updated. Generic examples throughout. No personal vault paths, no trading- domain terms. Pre-emptive grep clean. make build-index regenerated; check-index passes.
4 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Second Python-side bootstrap. Same multi-doc-per-PR shape as PRs #17, #18, #19. 3 docs (~467-576 lines), 6 rules.
`rules/index.json`: 74 → 80 entries (3 new families).
Rules added
PR #19 lesson applied
PR #19 inserted RULE blocks ABOVE existing constraint sections, producing duplicate free-form content. This PR REPLACES the constraint sections with RULE blocks (the canonical Bad/Good supersedes the prior `Constraint: ... Rationale: ...` shape). Net diff is +214/-38 because each replacement adds the RULE block's structured fields + Why + Bad/Good but removes the old constraint prose.
Pre-emptive checks
Test plan