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`