cleveragents/cleveragents-core

Fork 3

UAT: application/services/plan_lifecycle_service.py exceeds 500-line limit at 2,649 lines — must be split into focused modules #4112

New issue

Open

opened 2026-04-06 10:24:46 +00:00 by freemo · 1 comment

freemo commented

2026-04-06 10:24:46 +00:00

Owner

Metadata

Branch: refactor/plan-lifecycle-service-split
Commit Message: refactor(application): split plan_lifecycle_service.py into focused modules under 500 lines
Milestone: (none — backlog, see note below)
Parent Epic: (none provided — see orphan note below)

Backlog note: This issue was discovered during autonomous operation
on milestone v3.7.0. It does not block milestone completion and has been
placed in the backlog for human review and future milestone assignment.

Bug Report

Feature Area: Code Organization and Module Structure
Tested by: UAT tester instance uat-tester-code-org-001
Severity: Medium (CONTRIBUTING.md compliance violation)

What Was Tested

Checked all Python files in src/cleveragents/ for compliance with the 500-line file size limit specified in CONTRIBUTING.md line 399: "Keep files under 500 lines. Break large files into focused, cohesive modules."

Expected Behavior (from CONTRIBUTING.md)

All Python source files should be under 500 lines. Large files must be broken into focused, cohesive modules.

Actual Behavior

src/cleveragents/application/services/plan_lifecycle_service.py contains 2,649 lines — 5.3× the allowed limit.

Evidence

$ wc -l src/cleveragents/application/services/plan_lifecycle_service.py
2649 src/cleveragents/application/services/plan_lifecycle_service.py

The file mixes multiple concerns:

Plan state machine transitions
Plan execution orchestration
Plan lifecycle event emission
Plan validation and preflight checks
Plan resume/retry logic

Steps to Reproduce

wc -l src/cleveragents/application/services/plan_lifecycle_service.py

Suggested Fix

Split into focused modules:

plan_state_machine.py — state transitions
plan_lifecycle_events.py — event emission
plan_lifecycle_service.py — thin orchestrator (< 500 lines)

Code Location

src/cleveragents/application/services/plan_lifecycle_service.py

Subtasks

Audit plan_lifecycle_service.py and identify all distinct concerns/responsibilities
Extract state machine logic into plan_state_machine.py (< 500 lines)
Extract event emission logic into plan_lifecycle_events.py (< 500 lines)
Extract validation/preflight logic into plan_lifecycle_validators.py (< 500 lines)
Extract resume/retry logic into plan_lifecycle_retry.py (< 500 lines)
Refactor plan_lifecycle_service.py into a thin orchestrator (< 500 lines)
Update all import sites referencing the original module
Tests (Behave): Update/add unit test scenarios for each new module
Tests (Robot): Verify integration tests still pass after refactoring
Verify wc -l on all new files confirms each is under 500 lines
Verify coverage >= 97% via nox -s coverage_report
Run nox (all default sessions), fix any errors

Definition of Done

This issue is complete when:

All subtasks above are completed and checked off.
plan_lifecycle_service.py and all extracted modules are each under 500 lines.
No regressions: all existing behaviour is preserved and all tests pass.
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation.
The commit is pushed to the remote on the branch matching the Branch in Metadata exactly.
The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.
All nox stages pass.
Coverage >= 97%.

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-new-issue-creator

## Metadata - **Branch**: `refactor/plan-lifecycle-service-split` - **Commit Message**: `refactor(application): split plan_lifecycle_service.py into focused modules under 500 lines` - **Milestone**: *(none — backlog, see note below)* - **Parent Epic**: *(none provided — see orphan note below)* > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.7.0. It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. --- ## Bug Report **Feature Area:** Code Organization and Module Structure **Tested by:** UAT tester instance uat-tester-code-org-001 **Severity:** Medium (CONTRIBUTING.md compliance violation) ### What Was Tested Checked all Python files in `src/cleveragents/` for compliance with the 500-line file size limit specified in CONTRIBUTING.md line 399: *"Keep files under 500 lines. Break large files into focused, cohesive modules."* ### Expected Behavior (from CONTRIBUTING.md) All Python source files should be under 500 lines. Large files must be broken into focused, cohesive modules. ### Actual Behavior `src/cleveragents/application/services/plan_lifecycle_service.py` contains **2,649 lines** — **5.3× the allowed limit**. ### Evidence ``` $ wc -l src/cleveragents/application/services/plan_lifecycle_service.py 2649 src/cleveragents/application/services/plan_lifecycle_service.py ``` The file mixes multiple concerns: - Plan state machine transitions - Plan execution orchestration - Plan lifecycle event emission - Plan validation and preflight checks - Plan resume/retry logic ### Steps to Reproduce ```bash wc -l src/cleveragents/application/services/plan_lifecycle_service.py ``` ### Suggested Fix Split into focused modules: - `plan_state_machine.py` — state transitions - `plan_lifecycle_events.py` — event emission - `plan_lifecycle_service.py` — thin orchestrator (< 500 lines) ### Code Location `src/cleveragents/application/services/plan_lifecycle_service.py` --- ## Subtasks - [ ] Audit `plan_lifecycle_service.py` and identify all distinct concerns/responsibilities - [ ] Extract state machine logic into `plan_state_machine.py` (< 500 lines) - [ ] Extract event emission logic into `plan_lifecycle_events.py` (< 500 lines) - [ ] Extract validation/preflight logic into `plan_lifecycle_validators.py` (< 500 lines) - [ ] Extract resume/retry logic into `plan_lifecycle_retry.py` (< 500 lines) - [ ] Refactor `plan_lifecycle_service.py` into a thin orchestrator (< 500 lines) - [ ] Update all import sites referencing the original module - [ ] Tests (Behave): Update/add unit test scenarios for each new module - [ ] Tests (Robot): Verify integration tests still pass after refactoring - [ ] Verify `wc -l` on all new files confirms each is under 500 lines - [ ] Verify coverage >= 97% via `nox -s coverage_report` - [ ] Run `nox` (all default sessions), fix any errors ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - `plan_lifecycle_service.py` and all extracted modules are each under 500 lines. - No regressions: all existing behaviour is preserved and all tests pass. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly. - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done. - All nox stages pass. - Coverage >= 97%. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo commented

2026-04-06 10:25:10 +00:00

Author

Owner

⚠️ Orphan Issue — Needs Manual Epic Linking

This issue was created without a parent Epic because no suitable parent Epic was identified at creation time. Per CONTRIBUTING.md, all issues (except Epics and Legendaries) must be linked to a parent Epic.

Action required: A project maintainer should link this issue to the most appropriate parent Epic using Forgejo's dependency system (this issue should block the parent Epic).

Candidate parent Epics to consider:

#397 — Epic: Server & Autonomy Infrastructure (covers core application services)
#368 — Epic: Subplans & Parallelism (covers plan-related functionality)
Or create a new "Code Quality / Technical Debt" Epic if one does not yet exist.

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-new-issue-creator

⚠️ **Orphan Issue — Needs Manual Epic Linking** This issue was created without a parent Epic because no suitable parent Epic was identified at creation time. Per CONTRIBUTING.md, all issues (except Epics and Legendaries) must be linked to a parent Epic. **Action required:** A project maintainer should link this issue to the most appropriate parent Epic using Forgejo's dependency system (this issue should **block** the parent Epic). Candidate parent Epics to consider: - **#397** — Epic: Server & Autonomy Infrastructure (covers core application services) - **#368** — Epic: Subplans & Parallelism (covers plan-related functionality) - Or create a new "Code Quality / Technical Debt" Epic if one does not yet exist. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo added the

Points

label

2026-04-06 10:26:45 +00:00

freemo referenced this issue

2026-04-06 10:28:18 +00:00

[Automated] CleverAgents Build Session - 2026-04-06 #3775

freemo referenced this issue

2026-04-06 10:35:53 +00:00

[Automated] CleverAgents Build Session - 2026-04-06 #3775

freemo referenced this issue

2026-04-06 10:39:53 +00:00