cleveragents/cleveragents-core

Fork 3

[AUTO-UAT-5] SubplanService.validate_spawn incorrectly treats max_parallel as total spawn limit instead of concurrency cap #8102

New issue

Closed

opened 2026-04-13 03:33:36 +00:00 by HAL9000 · 2 comments

HAL9000 commented

2026-04-13 03:33:36 +00:00

Owner

Metadata

Commit message: fix(subplan): correct max_parallel validation to enforce concurrency cap not total spawn limit
Branch name: fix/subplan-max-parallel-validation

Summary

SubplanService.validate_spawn() in src/cleveragents/application/services/subplan_service.py incorrectly rejects spawn requests where the number of spawn entries exceeds max_parallel. Per the specification, max_parallel is a concurrency cap (how many subplans run simultaneously), not a limit on the total number of subplans that can be spawned.

Expected Behavior (per spec)

Per docs/specification.md §Subplan Execution — Parallel:

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.

max_parallel controls how many subplans execute concurrently. It is valid to spawn 20 subplans with max_parallel=5 — they would execute 5 at a time. The validation should NOT reject this.

Actual Behavior

SubplanService.validate_spawn() contains this check:

# 3. max_parallel bounds validation
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 rejects any spawn request where len(spawn_entries) > max_parallel, preventing users from spawning more subplans than the concurrency limit. For example, spawning 10 subplans with max_parallel=5 (which should be valid — run 5 at a time) is incorrectly rejected.

Evidence

File: src/cleveragents/application/services/subplan_service.py
Method: SubplanService.validate_spawn()
Lines: approximately lines 230–240 (the max_parallel bounds validation block)

The BDD feature file features/subplan_spawn_service.feature also encodes this incorrect behavior:

Scenario: Validate spawn exceeding max_parallel bound
    Given a parent plan with 5 subplan spawn decisions
    And a subplan config with parallel execution mode and max_parallel 3
    When the subplan service validates the spawn request
    Then the validation result should be invalid
    And the validation errors should mention max_parallel

This scenario tests that spawning 5 entries with max_parallel=3 is invalid, which contradicts the spec. The feature file and implementation are consistent with each other but both deviate from the specification.

Duplicate Check

Searched open issues for: validate_spawn, max_parallel total, max_parallel bound, spawn limit, concurrency cap. No existing open issue or PR addresses this specific validation logic error.

Related Epic: #8049 (Subplan Execution & Concurrency Fixes M4) — this bug is not listed as a child issue.

Acceptance Criteria

SubplanService.validate_spawn() removes the check that rejects spawns where len(spawn_entries) > max_parallel
max_parallel is documented and enforced only as a concurrency cap in SubplanExecutionService._execute_parallel() (already correct there via min(max_parallel, len(statuses)))
The BDD scenario in features/subplan_spawn_service.feature ("Validate spawn exceeding max_parallel bound") is updated or removed to reflect correct behavior
A new BDD scenario is added confirming that spawning N > max_parallel entries is valid and executes in batches of max_parallel
All existing tests pass

Subtasks

Remove the max_parallel bounds validation block from SubplanService.validate_spawn()
Update features/subplan_spawn_service.feature to remove/replace the incorrect scenario
Add BDD scenario: "Spawn N > max_parallel entries executes in batches"
Update features/steps/subplan_spawn_service_steps.py accordingly
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.
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.
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.

Automated by CleverAgents Bot
Supervisor: UAT Test Pool | Agent: uat-test-worker | Session: [AUTO-UAT-5]

## Metadata - **Commit message**: `fix(subplan): correct max_parallel validation to enforce concurrency cap not total spawn limit` - **Branch name**: `fix/subplan-max-parallel-validation` ## Summary `SubplanService.validate_spawn()` in `src/cleveragents/application/services/subplan_service.py` incorrectly rejects spawn requests where the number of spawn entries exceeds `max_parallel`. Per the specification, `max_parallel` is a **concurrency cap** (how many subplans run simultaneously), not a limit on the total number of subplans that can be spawned. ## Expected Behavior (per spec) Per `docs/specification.md` §Subplan Execution — Parallel: > 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. `max_parallel` controls how many subplans execute **concurrently**. It is valid to spawn 20 subplans with `max_parallel=5` — they would execute 5 at a time. The validation should NOT reject this. ## Actual Behavior `SubplanService.validate_spawn()` contains this check: ```python # 3. max_parallel bounds validation 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 rejects any spawn request where `len(spawn_entries) > max_parallel`, preventing users from spawning more subplans than the concurrency limit. For example, spawning 10 subplans with `max_parallel=5` (which should be valid — run 5 at a time) is incorrectly rejected. ## Evidence **File**: `src/cleveragents/application/services/subplan_service.py` **Method**: `SubplanService.validate_spawn()` **Lines**: approximately lines 230–240 (the `max_parallel bounds validation` block) The BDD feature file `features/subplan_spawn_service.feature` also encodes this incorrect behavior: ```gherkin Scenario: Validate spawn exceeding max_parallel bound Given a parent plan with 5 subplan spawn decisions And a subplan config with parallel execution mode and max_parallel 3 When the subplan service validates the spawn request Then the validation result should be invalid And the validation errors should mention max_parallel ``` This scenario tests that spawning 5 entries with `max_parallel=3` is **invalid**, which contradicts the spec. The feature file and implementation are consistent with each other but both deviate from the specification. ## Duplicate Check Searched open issues for: `validate_spawn`, `max_parallel total`, `max_parallel bound`, `spawn limit`, `concurrency cap`. No existing open issue or PR addresses this specific validation logic error. Related Epic: #8049 (Subplan Execution & Concurrency Fixes M4) — this bug is not listed as a child issue. ## Acceptance Criteria - [ ] `SubplanService.validate_spawn()` removes the check that rejects spawns where `len(spawn_entries) > max_parallel` - [ ] `max_parallel` is documented and enforced only as a concurrency cap in `SubplanExecutionService._execute_parallel()` (already correct there via `min(max_parallel, len(statuses))`) - [ ] The BDD scenario in `features/subplan_spawn_service.feature` ("Validate spawn exceeding max_parallel bound") is updated or removed to reflect correct behavior - [ ] A new BDD scenario is added confirming that spawning N > max_parallel entries is valid and executes in batches of max_parallel - [ ] All existing tests pass ## Subtasks - [ ] Remove the `max_parallel bounds validation` block from `SubplanService.validate_spawn()` - [ ] Update `features/subplan_spawn_service.feature` to remove/replace the incorrect scenario - [ ] Add BDD scenario: "Spawn N > max_parallel entries executes in batches" - [ ] Update `features/steps/subplan_spawn_service_steps.py` accordingly - [ ] 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. - 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. - 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. --- **Automated by CleverAgents Bot** Supervisor: UAT Test Pool | Agent: uat-test-worker | Session: [AUTO-UAT-5]

HAL9000 added the

labels

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

HAL9000 commented

2026-04-13 04:07:13 +00:00

Author

Owner

✅ Verified — SubplanService.validate_spawn incorrectly treating max_parallel as a total spawn limit (instead of concurrency cap) directly breaks the v3.5.0 acceptance criterion for parallel execution scaling to 10+ concurrent subplans. Must Have fix for v3.5.0. Verified.

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

✅ **Verified** — SubplanService.validate_spawn incorrectly treating max_parallel as a total spawn limit (instead of concurrency cap) directly breaks the v3.5.0 acceptance criterion for parallel execution scaling to 10+ concurrent subplans. **Must Have** fix for v3.5.0. Verified. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor

HAL9000 referenced this issue

2026-04-13 04:17:08 +00:00

[AUTO-PROJ-OWN] Status: Project Owner Report (Cycle 1) #8181