UAT: `SubplanService.validate_spawn()` incorrectly rejects valid parallel spawn requests when `len(entries) > max_parallel` #2058

New issue

Open

opened 2026-04-03 03:45:24 +00:00 by freemo · 1 comment

freemo commented

2026-04-03 03:45:24 +00:00

Owner

Metadata

Branch: fix/subplan-service-validate-spawn-max-parallel
Commit Message: fix(subplan): remove incorrect max_parallel spawn count validation in SubplanService.validate_spawn()
Milestone: v3.7.0
Parent Epic: No open Plan lifecycle Epic found — see orphan note below

Description

The SubplanService.validate_spawn() method in
src/cleveragents/application/services/subplan_service.py (lines 362–369)
incorrectly rejects spawn requests where the number of spawn entries exceeds
max_parallel. This is a spec-alignment bug.

Expected Behaviour (per spec)

The specification (docs/specification.md §Child Plan Execution Modes,
line 18417) states:

"Parallel execution is bounded by SubplanConfig.max_parallel (default:
5, range: 1–50). This cap prevents runaway resource consumption when a
large number of child plans are spawned simultaneously. The runtime uses a
ThreadPoolExecutor with min(max_parallel, len(subplans)) workers."

The min(max_parallel, len(subplans)) formula explicitly allows spawning
MORE subplans than max_parallel — they simply run in batches.
max_parallel is a concurrency cap, not a spawn count limit.

Actual Behaviour

The current validation code:

if config.execution_mode == ExecutionMode.PARALLEL:
    entry_count: int = len(spawn_entries)
    if entry_count > config.max_parallel:
        errors.append(
            f"Number of spawn entries ({entry_count}) exceeds "
            f"max_parallel bound ({config.max_parallel})"
        )

This incorrectly raises SpawnValidationError for a spawn request with
10 entries and max_parallel=5, even though the spec explicitly supports
this case (they would run 5 at a time in batches).

Steps to Reproduce

Create a SubplanConfig with execution_mode=PARALLEL and max_parallel=5
Create 6 or more SpawnEntry objects
Call SubplanService.validate_spawn(config, entries)
Observe: SpawnValidationError is raised with "Number of spawn entries
(6) exceeds max_parallel bound (5)"
Expected: Validation passes; the 6 entries run in batches of 5

Code Location

src/cleveragents/application/services/subplan_service.py, lines 362–369

Fix Direction

Remove validation check #3 (max_parallel bounds validation) from
validate_spawn(). The max_parallel cap is enforced at execution time by
ThreadPoolExecutor(max_workers=min(max_parallel, len(statuses))) in
SubplanExecutionService._execute_parallel().

Subtasks

Remove the entry_count > config.max_parallel guard block (lines 362–369) from SubplanService.validate_spawn()
Verify no other callers in the codebase rely on this incorrect validation behaviour
Update or add Behave unit test scenarios in features/ to assert that validate_spawn() accepts len(entries) > max_parallel for PARALLEL mode
Update or add Behave unit test scenarios asserting that max_parallel is still enforced as a concurrency cap at execution time in SubplanExecutionService._execute_parallel()
Run nox -e typecheck to confirm no type regressions
Run nox -e unit_tests and nox -e coverage_report to confirm all tests pass and coverage ≥ 97%

Definition of Done

The incorrect entry_count > config.max_parallel validation block is removed from validate_spawn()
SubplanService.validate_spawn() accepts spawn requests where len(entries) > max_parallel for ExecutionMode.PARALLEL
Behave unit tests cover the corrected behaviour (both the previously-rejected case and the existing valid rejection cases)
All nox stages pass (nox -e lint, nox -e typecheck, nox -e unit_tests, nox -e integration_tests)
Coverage ≥ 97%
Commit pushed to fix/subplan-service-validate-spawn-max-parallel with message fix(subplan): remove incorrect max_parallel spawn count validation in SubplanService.validate_spawn() and footer ISSUES CLOSED: #<this issue number>
Associated PR merged

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-uat-tester

## Metadata - **Branch**: `fix/subplan-service-validate-spawn-max-parallel` - **Commit Message**: `fix(subplan): remove incorrect max_parallel spawn count validation in SubplanService.validate_spawn()` - **Milestone**: v3.7.0 - **Parent Epic**: _No open Plan lifecycle Epic found — see orphan note below_ ## Description The `SubplanService.validate_spawn()` method in `src/cleveragents/application/services/subplan_service.py` (lines 362–369) incorrectly rejects spawn requests where the number of spawn entries exceeds `max_parallel`. This is a spec-alignment bug. ### Expected Behaviour (per spec) The specification (`docs/specification.md` §Child Plan Execution Modes, line 18417) states: > "Parallel execution is bounded by `SubplanConfig.max_parallel` (default: > `5`, range: 1–50). This cap prevents runaway resource consumption when a > large number of child plans are spawned simultaneously. The runtime uses a > `ThreadPoolExecutor` with `min(max_parallel, len(subplans))` workers." The `min(max_parallel, len(subplans))` formula **explicitly allows spawning MORE subplans than `max_parallel`** — they simply run in batches. `max_parallel` is a **concurrency cap**, not a spawn count limit. ### Actual Behaviour The current validation code: ```python if config.execution_mode == ExecutionMode.PARALLEL: entry_count: int = len(spawn_entries) if entry_count > config.max_parallel: errors.append( f"Number of spawn entries ({entry_count}) exceeds " f"max_parallel bound ({config.max_parallel})" ) ``` This incorrectly raises `SpawnValidationError` for a spawn request with 10 entries and `max_parallel=5`, even though the spec explicitly supports this case (they would run 5 at a time in batches). ### Steps to Reproduce 1. Create a `SubplanConfig` with `execution_mode=PARALLEL` and `max_parallel=5` 2. Create 6 or more `SpawnEntry` objects 3. Call `SubplanService.validate_spawn(config, entries)` 4. **Observe:** `SpawnValidationError` is raised with "Number of spawn entries (6) exceeds max_parallel bound (5)" 5. **Expected:** Validation passes; the 6 entries run in batches of 5 ### Code Location `src/cleveragents/application/services/subplan_service.py`, lines 362–369 ### Fix Direction Remove validation check #3 (max_parallel bounds validation) from `validate_spawn()`. The `max_parallel` cap is enforced at execution time by `ThreadPoolExecutor(max_workers=min(max_parallel, len(statuses)))` in `SubplanExecutionService._execute_parallel()`. ## Subtasks - [ ] Remove the `entry_count > config.max_parallel` guard block (lines 362–369) from `SubplanService.validate_spawn()` - [ ] Verify no other callers in the codebase rely on this incorrect validation behaviour - [ ] Update or add Behave unit test scenarios in `features/` to assert that `validate_spawn()` accepts `len(entries) > max_parallel` for `PARALLEL` mode - [ ] Update or add Behave unit test scenarios asserting that `max_parallel` is still enforced as a concurrency cap at execution time in `SubplanExecutionService._execute_parallel()` - [ ] Run `nox -e typecheck` to confirm no type regressions - [ ] Run `nox -e unit_tests` and `nox -e coverage_report` to confirm all tests pass and coverage ≥ 97% ## Definition of Done - [ ] The incorrect `entry_count > config.max_parallel` validation block is removed from `validate_spawn()` - [ ] `SubplanService.validate_spawn()` accepts spawn requests where `len(entries) > max_parallel` for `ExecutionMode.PARALLEL` - [ ] Behave unit tests cover the corrected behaviour (both the previously-rejected case and the existing valid rejection cases) - [ ] All nox stages pass (`nox -e lint`, `nox -e typecheck`, `nox -e unit_tests`, `nox -e integration_tests`) - [ ] Coverage ≥ 97% - [ ] Commit pushed to `fix/subplan-service-validate-spawn-max-parallel` with message `fix(subplan): remove incorrect max_parallel spawn count validation in SubplanService.validate_spawn()` and footer `ISSUES CLOSED: #<this issue number>` - [ ] Associated PR merged --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-uat-tester

freemo added this to the v3.7.0 milestone

2026-04-03 03:45:28 +00:00

freemo commented

2026-04-03 03:45:44 +00:00

Author

Owner

⚠️ Orphan Issue — Manual Linking Required

A search of all open issues in cleveragents/cleveragents-core found no open Epic covering the Plan lifecycle / SubplanService domain. This issue cannot be automatically linked to a parent Epic.

Action required (project owner): Please identify or create the appropriate parent Epic for Plan lifecycle / child plan execution work, then:

Link this issue as a child of that Epic using Forgejo's dependency system (this issue blocks the parent Epic).
Update the ## Metadata → Parent Epic field in the issue body with the correct Epic number.

Until this is done, issue #2058 is an orphan and does not comply with the CONTRIBUTING.md requirement that all issues be linked to a parent Epic.

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

⚠️ **Orphan Issue — Manual Linking Required** A search of all open issues in `cleveragents/cleveragents-core` found **no open Epic** covering the Plan lifecycle / SubplanService domain. This issue cannot be automatically linked to a parent Epic. **Action required (project owner):** Please identify or create the appropriate parent Epic for Plan lifecycle / child plan execution work, then: 1. Link this issue as a child of that Epic using Forgejo's dependency system (this issue **blocks** the parent Epic). 2. Update the `## Metadata` → `Parent Epic` field in the issue body with the correct Epic number. Until this is done, issue #2058 is an **orphan** and does not comply with the CONTRIBUTING.md requirement that all issues be linked to a parent Epic. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo referenced this issue

2026-04-03 03:46:06 +00:00

[CA-AUTO] UAT Pool Supervisor — v3.7.0 — Session Tracker #2023

freemo referenced this issue

2026-04-03 03:51:03 +00:00

[CA-AUTO] UAT Pool Supervisor — v3.7.0 — Session Tracker #2023

freemo referenced this issue

2026-04-03 03:51:15 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 691 — v3.7.0 #2079

freemo referenced this issue

2026-04-03 03:57:57 +00:00

[CA-AUTO] UAT Pool Supervisor — v3.7.0 — Session Tracker #2023