[AUTO-GUARD-1] Technical Debt: plan_lifecycle_service.py is a 2741-line god class with 50+ functions #9949

Open
opened 2026-04-16 06:53:01 +00:00 by HAL9000 · 0 comments
Owner

Metadata

  • Commit Message: refactor(services): split PlanLifecycleService god class into focused sub-services
  • Branch: refactor/auto-guard-1-plan-lifecycle-service-split

Background and Context

src/cleveragents/application/services/plan_lifecycle_service.py is a 2741-line file containing a single service class with over 50 methods. This violates the Single Responsibility Principle and makes the file extremely difficult to maintain, test, and reason about.

File: src/cleveragents/application/services/plan_lifecycle_service.py
Lines: 2741
Function count: 50+ methods

Functions identified (partial list):

  • create_action (line 729) — action creation logic
  • use_action (line 978) — action usage logic (~158 lines)
  • execute_plan (line 1506) — plan execution (~106 lines)
  • apply_plan (line 1719) — plan apply logic (~80 lines)
  • complete_apply (line 1821) — apply completion (~93 lines)
  • prompt_plan (line 1981) — plan prompting (~97 lines)
  • cancel_plan (line 2078) — plan cancellation (~80 lines)
  • auto_progress (line 2319) — auto-progression logic (~45 lines)
  • try_auto_run (line 2364) — auto-run logic (~82 lines)
  • _perform_reversion (line 2688) — reversion logic

Impact

  • Functions like use_action (lines 978–1135, ~158 lines) and execute_plan (lines 1506–1611, ~106 lines) exceed the 50-line threshold
  • The class mixes action management, plan lifecycle, estimation, invariant reconciliation, and correction subscription concerns
  • 340+ except Exception patterns across the codebase, with this file contributing significantly (lines 285, 322, 384, 391, 484, 492, 515, 547, 575, 715, 1060, 1126, 1456, 1496, 1592, 1674, 1706, 1901, 1968, 2052, 2143, 2179, 2311)

Expected Behavior

PlanLifecycleService is decomposed into focused, single-responsibility sub-services. Each sub-service has a clear bounded context, all methods stay within the 50-line threshold, and the codebase is easier to test, maintain, and reason about.

Acceptance Criteria

  • PlanLifecycleService is split into at least 4 focused sub-services (see Subtasks)
  • No individual method exceeds 50 lines
  • All except Exception catch-alls in the affected files are replaced with specific exception types
  • All existing tests pass after the refactor
  • Test coverage remains ≥ 97%
  • nox passes across the entire codebase with no new failures

Subtasks

  • Extract ActionManagementService — action CRUD operations (create_action, use_action, and related helpers)
  • Extract PlanExecutionService — execute/apply/cancel lifecycle (execute_plan, apply_plan, complete_apply, cancel_plan)
  • Extract PlanCorrectionService — correction and reversion logic (_perform_reversion, correction subscription handlers)
  • Extract PlanEstimationService — estimation and invariant reconciliation concerns
  • Refactor auto_progress and try_auto_run into the appropriate sub-service
  • Replace all bare except Exception patterns in affected files with specific exception types
  • Update all import sites and dependency injection wiring to reference the new sub-services
  • Verify coverage ≥ 97% via nox -s coverage_report; write additional Behave-style unit tests if needed
  • Run nox (all default sessions, including benchmark) and fix any errors

Definition of Done

This issue is closed when:

  • All subtasks above are checked off
  • PlanLifecycleService no longer exists as a monolithic god class
  • All new sub-services are individually testable and covered at ≥ 97%
  • A pull request is merged to master with a commit message matching the Metadata above
  • No regressions are introduced in any existing test suite

References

  • ADR-006: Plan Lifecycle
  • src/cleveragents/application/services/plan_lifecycle_service.py

Automated by CleverAgents Bot
Agent: new-issue-creator

## Metadata - **Commit Message:** `refactor(services): split PlanLifecycleService god class into focused sub-services` - **Branch:** `refactor/auto-guard-1-plan-lifecycle-service-split` ## Background and Context `src/cleveragents/application/services/plan_lifecycle_service.py` is a 2741-line file containing a single service class with over 50 methods. This violates the Single Responsibility Principle and makes the file extremely difficult to maintain, test, and reason about. **File:** `src/cleveragents/application/services/plan_lifecycle_service.py` **Lines:** 2741 **Function count:** 50+ methods ### Functions identified (partial list): - `create_action` (line 729) — action creation logic - `use_action` (line 978) — action usage logic (~158 lines) - `execute_plan` (line 1506) — plan execution (~106 lines) - `apply_plan` (line 1719) — plan apply logic (~80 lines) - `complete_apply` (line 1821) — apply completion (~93 lines) - `prompt_plan` (line 1981) — plan prompting (~97 lines) - `cancel_plan` (line 2078) — plan cancellation (~80 lines) - `auto_progress` (line 2319) — auto-progression logic (~45 lines) - `try_auto_run` (line 2364) — auto-run logic (~82 lines) - `_perform_reversion` (line 2688) — reversion logic ### Impact - Functions like `use_action` (lines 978–1135, ~158 lines) and `execute_plan` (lines 1506–1611, ~106 lines) exceed the 50-line threshold - The class mixes action management, plan lifecycle, estimation, invariant reconciliation, and correction subscription concerns - 340+ `except Exception` patterns across the codebase, with this file contributing significantly (lines 285, 322, 384, 391, 484, 492, 515, 547, 575, 715, 1060, 1126, 1456, 1496, 1592, 1674, 1706, 1901, 1968, 2052, 2143, 2179, 2311) ## Expected Behavior `PlanLifecycleService` is decomposed into focused, single-responsibility sub-services. Each sub-service has a clear bounded context, all methods stay within the 50-line threshold, and the codebase is easier to test, maintain, and reason about. ## Acceptance Criteria - [ ] `PlanLifecycleService` is split into at least 4 focused sub-services (see Subtasks) - [ ] No individual method exceeds 50 lines - [ ] All `except Exception` catch-alls in the affected files are replaced with specific exception types - [ ] All existing tests pass after the refactor - [ ] Test coverage remains ≥ 97% - [ ] `nox` passes across the entire codebase with no new failures ## Subtasks - [ ] Extract `ActionManagementService` — action CRUD operations (`create_action`, `use_action`, and related helpers) - [ ] Extract `PlanExecutionService` — execute/apply/cancel lifecycle (`execute_plan`, `apply_plan`, `complete_apply`, `cancel_plan`) - [ ] Extract `PlanCorrectionService` — correction and reversion logic (`_perform_reversion`, correction subscription handlers) - [ ] Extract `PlanEstimationService` — estimation and invariant reconciliation concerns - [ ] Refactor `auto_progress` and `try_auto_run` into the appropriate sub-service - [ ] Replace all bare `except Exception` patterns in affected files with specific exception types - [ ] Update all import sites and dependency injection wiring to reference the new sub-services - [ ] Verify coverage ≥ 97% via `nox -s coverage_report`; write additional Behave-style unit tests if needed - [ ] Run `nox` (all default sessions, including benchmark) and fix any errors ## Definition of Done This issue is closed when: - All subtasks above are checked off - `PlanLifecycleService` no longer exists as a monolithic god class - All new sub-services are individually testable and covered at ≥ 97% - A pull request is merged to `master` with a commit message matching the Metadata above - No regressions are introduced in any existing test suite ## References - ADR-006: Plan Lifecycle - `src/cleveragents/application/services/plan_lifecycle_service.py` --- **Automated by CleverAgents Bot** Agent: new-issue-creator
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
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#9949
No description provided.