From a3bcc7b0ee9fe529be1467b8911aecda7346a7d4 Mon Sep 17 00:00:00 2001 From: Alexander Whitestone Date: Tue, 24 Mar 2026 14:13:05 -0400 Subject: [PATCH] docs: add Commit Discipline section to CLAUDE.md Adds a dedicated "Commit Discipline" section with explicit PR size limits (<150 lines target, >200 lines must split), one-concern-per-PR rule, commit-by-function table, decomposition rules, and the modularization epic exception. Fixes #429 --- CLAUDE.md | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 5b228d2..ec2ce5b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -104,6 +104,40 @@ Issues must be addressed one at a time. Only one PR open at a time. | 12 | #16 — Session power meter — 3D balance visualizer | pending | | 13 | #18 — Unified memory graph & sovereignty loop visualization | pending | +## Commit Discipline + +**Every PR must focus on exactly ONE concern. No exceptions.** + +### PR Size Limits + +- **Target: <150 lines changed per PR.** This is the default ceiling. +- **Hard limit: >200 lines → split into sequential PRs.** If your change exceeds 200 lines, stop and decompose it before opening a PR. +- **One concern per PR**: data layer, logic, OR visuals — never mixed in a single PR. + +### Commit by Function + +Use the concern as a commit scope prefix: + +| Concern | Example commit message | +|---------|----------------------| +| Data layer | `feat: data-provider for agent status` | +| Visual / style | `style: neon-update on portal ring` | +| Refactor | `refactor: extract ticker from app.js` | +| Fix | `fix: portal health-check timeout` | +| Process / docs | `chore: update CLAUDE.md commit rules` | + +### Decomposition Rules + +When a feature spans multiple concerns (e.g. new data + new visual): + +1. Open a PR for the data module first. Wait for merge. +2. Open a PR for the visual module that reads from state. Wait for merge. +3. Never combine data + visual work in one PR. + +### Exception: Modularization Epics + +Large refactors tracked as a numbered epic (e.g. #409) may use one PR per *phase*, where each phase is a logical, atomic unit of the refactor. Phases must still target <150 lines where possible and must not mix unrelated concerns. + ## PR Rules - Base every PR on latest `main` -- 2.43.0