Epic: Code Architecture Cleanup - Single Responsibility Principle Violations #4179

Open
opened 2026-04-06 16:19:03 +00:00 by freemo · 2 comments
Owner

Epic: Code Architecture Cleanup

Consolidates 16+ individual refactoring issues identified by Architecture Guard

Problem Statement

The automated Architecture Guard has identified numerous Single Responsibility Principle violations across the codebase where large files mix multiple concerns (data models, business logic, protocols, enums) and exceed the 500-line guideline.

Scope

This epic consolidates the following types of violations:

Critical Plan Lifecycle Files (High Priority)

  • plan.py (1200+ lines) - Core plan models mixed with business logic
  • correction.py - Mixed correction models and handlers
  • models.py (domain) - Multiple large model files

Infrastructure Files (Medium Priority)

  • checkpoint.py - Protocol + model + service logic
  • tool.py - Tool models and execution logic
  • session.py - Session models and management
  • repositories.py - Repository patterns mixed with models

Resource & Context Files (Lower Priority)

  • resource_type.py - Resource models and handlers
  • context_fragment.py - Context models and processing
  • context_policy.py - Policy models and enforcement
  • invariant.py - Invariant models and validation

Architecture Principles

All refactoring should follow:

  1. Single Responsibility Principle - One concern per module
  2. Layer Separation - Keep domain, application, infrastructure separate
  3. Protocol Extraction - Move protocols to dedicated files
  4. Model Grouping - Related models in focused files
  5. Service Isolation - Business logic in application layer

Acceptance Criteria

  • No source file exceeds 500 lines (guideline)
  • Each module has a single, clear responsibility
  • Protocols separated from implementations
  • Domain models separated from business logic
  • Test coverage maintained ≥97%
  • All existing functionality preserved

Implementation Strategy

Phase 1 (v3.3.0): Critical plan lifecycle files
Phase 2 (v3.4.0): Infrastructure components
Phase 3 (v3.5.0+): Resource and context modules

Replaces Individual Issues

This epic replaces and consolidates issues #4161, #4172, #4170, #4168, #4166, #4164, #4163, #4158, #4167, #4165, #4162, #4159, #4157, #4169, and related refactoring issues identified by Architecture Guard.


Milestone: v3.3.0+ (Deferred - Focus on Core Functionality First)
Priority: Should Have (Code Quality)
Estimated Effort: 8-12 story points across multiple phases

## Epic: Code Architecture Cleanup **Consolidates 16+ individual refactoring issues identified by Architecture Guard** ### Problem Statement The automated Architecture Guard has identified numerous Single Responsibility Principle violations across the codebase where large files mix multiple concerns (data models, business logic, protocols, enums) and exceed the 500-line guideline. ### Scope This epic consolidates the following types of violations: #### **Critical Plan Lifecycle Files** (High Priority) - `plan.py` (1200+ lines) - Core plan models mixed with business logic - `correction.py` - Mixed correction models and handlers - `models.py` (domain) - Multiple large model files #### **Infrastructure Files** (Medium Priority) - `checkpoint.py` - Protocol + model + service logic - `tool.py` - Tool models and execution logic - `session.py` - Session models and management - `repositories.py` - Repository patterns mixed with models #### **Resource & Context Files** (Lower Priority) - `resource_type.py` - Resource models and handlers - `context_fragment.py` - Context models and processing - `context_policy.py` - Policy models and enforcement - `invariant.py` - Invariant models and validation ### Architecture Principles All refactoring should follow: 1. **Single Responsibility Principle** - One concern per module 2. **Layer Separation** - Keep domain, application, infrastructure separate 3. **Protocol Extraction** - Move protocols to dedicated files 4. **Model Grouping** - Related models in focused files 5. **Service Isolation** - Business logic in application layer ### Acceptance Criteria - [ ] No source file exceeds 500 lines (guideline) - [ ] Each module has a single, clear responsibility - [ ] Protocols separated from implementations - [ ] Domain models separated from business logic - [ ] Test coverage maintained ≥97% - [ ] All existing functionality preserved ### Implementation Strategy **Phase 1 (v3.3.0):** Critical plan lifecycle files **Phase 2 (v3.4.0):** Infrastructure components **Phase 3 (v3.5.0+):** Resource and context modules ### Replaces Individual Issues This epic replaces and consolidates issues #4161, #4172, #4170, #4168, #4166, #4164, #4163, #4158, #4167, #4165, #4162, #4159, #4157, #4169, and related refactoring issues identified by Architecture Guard. --- **Milestone:** v3.3.0+ (Deferred - Focus on Core Functionality First) **Priority:** Should Have (Code Quality) **Estimated Effort:** 8-12 story points across multiple phases
freemo added this to the v3.5.0 milestone 2026-04-06 17:49:08 +00:00
freemo modified the milestone from v3.5.0 to v3.6.0 2026-04-06 18:44:36 +00:00
freemo removed this from the v3.6.0 milestone 2026-04-06 21:07:03 +00:00
Owner

Issue triaged by project owner:

  • State: Verified — Valid Epic consolidating 16+ architecture cleanup issues from Architecture Guard
  • Priority: Medium (already set) — Important for code quality but not blocking features
  • MoSCoW: Should Have (already set) — SRP violations should be addressed for maintainability
  • Assignee: HAL9000

This is a refactoring Epic that consolidates architecture guard findings. It should be worked on when there's capacity between milestone-critical work.


Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: project-owner

Issue triaged by project owner: - **State**: Verified ✅ — Valid Epic consolidating 16+ architecture cleanup issues from Architecture Guard - **Priority**: Medium ✅ (already set) — Important for code quality but not blocking features - **MoSCoW**: Should Have ✅ (already set) — SRP violations should be addressed for maintainability - **Assignee**: HAL9000 This is a refactoring Epic that consolidates architecture guard findings. It should be worked on when there's capacity between milestone-critical work. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner
HAL9000 self-assigned this 2026-04-08 14:03:02 +00:00
Owner

Label compliance fix applied:

  • Added missing label: State/Unverified
  • Reason: Issue had no State/* label. Per CONTRIBUTING.md, every issue must have exactly one State/* label. Added State/Unverified as the default for an Epic without a verified state.

Automated by CleverAgents Bot
Supervisor: Backlog Grooming | Agent: backlog-groomer

Label compliance fix applied: - Added missing label: `State/Unverified` - Reason: Issue had no State/* label. Per CONTRIBUTING.md, every issue must have exactly one State/* label. Added `State/Unverified` as the default for an Epic without a verified state. --- **Automated by CleverAgents Bot** Supervisor: Backlog Grooming | Agent: backlog-groomer
HAL9000 added this to the v3.5.0 milestone 2026-04-09 03:12:37 +00:00
Sign in to join this conversation.
No milestone
No project
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
cleveragents/cleveragents-core#4179
No description provided.