cleveragents/cleveragents-core

Fork 3

UAT: `ExecutionMode.DEPENDENCY_ORDERED` is not defined in the specification — undocumented third execution mode added to implementation #2074

New issue

Open

opened 2026-04-03 03:49:47 +00:00 by freemo · 1 comment

freemo commented

2026-04-03 03:49:47 +00:00

Owner

Metadata

Branch: fix/execution-mode-dependency-ordered-undocumented
Commit Message: fix(plan): remove or document undocumented DEPENDENCY_ORDERED execution mode
Milestone: v3.7.0
Parent Epic: #368

Description

The ExecutionMode enum in src/cleveragents/domain/models/core/plan.py defines three execution modes: SEQUENTIAL, PARALLEL, and DEPENDENCY_ORDERED. However, the specification only defines two execution modes: Sequential and Parallel. The DEPENDENCY_ORDERED mode is an undocumented extension not covered by the spec.

Expected behavior (from spec)

The spec (docs/specification.md §Child Plan Execution Modes, lines 18407–18418) defines exactly two execution modes:

Sequential: "Individual subplan_spawn decisions without a subplan_parallel_spawn wrapper execute one after another. If one fails, subsequent child plans are not started."
Parallel: "Multiple subplan_spawn decisions grouped under a subplan_parallel_spawn decision execute concurrently. If one fails, others can continue."

No third mode is mentioned anywhere in the specification.

Actual behavior

The implementation adds a third mode:

class ExecutionMode(StrEnum):
    SEQUENTIAL = "sequential"  # One after another, ordered by sequence
    PARALLEL = "parallel"  # All at once (up to max_parallel)
    DEPENDENCY_ORDERED = "dependency_ordered"  # Respect DAG dependencies

This mode is fully implemented in SubplanExecutionService._execute_dependency_ordered() with topological sort logic. It is also accepted as a valid value in SubplanConfig.execution_mode.

Problems caused

The DEPENDENCY_ORDERED mode is not in the spec, so its behavior is undefined from a product perspective.
Users/actors that set execution_mode: dependency_ordered in their configs are using an undocumented feature that may change or be removed.
The SubplanFailureHandler.should_stop_others() returns False for DEPENDENCY_ORDERED (since it's not SEQUENTIAL), meaning failure behavior is undefined by spec.
The builtin/plan-subplan tool's input schema does not expose dependency_ordered as a valid merge strategy option, creating an inconsistency.

Code locations

src/cleveragents/domain/models/core/plan.py, line 157: DEPENDENCY_ORDERED = "dependency_ordered"
src/cleveragents/application/services/subplan_execution_service.py, lines 338–412: _execute_dependency_ordered() implementation
src/cleveragents/application/services/subplan_service.py, lines 362–369: validation references ExecutionMode.DEPENDENCY_ORDERED

Resolution options

Either:

(a) Remove DEPENDENCY_ORDERED from the implementation until it is added to the spec, OR
(b) Update the specification to document this mode and its failure semantics

Subtasks

Confirm with product owner whether DEPENDENCY_ORDERED should be removed or spec-documented
If removing: delete ExecutionMode.DEPENDENCY_ORDERED from plan.py, remove _execute_dependency_ordered() from SubplanExecutionService, and update all references in subplan_service.py
If documenting: add §Child Plan Execution Modes entry to docs/specification.md covering behavior, failure semantics, and DAG constraints
Update SubplanFailureHandler.should_stop_others() to handle all defined modes explicitly (no implicit fallthrough)
Update builtin/plan-subplan tool input schema to be consistent with the final set of valid execution_mode values
Write/update Behave unit tests in features/ for the affected code paths
Ensure nox -e typecheck passes (Pyright)
Ensure nox -e unit_tests passes
Ensure nox -e coverage_report shows ≥ 97% coverage

Definition of Done

ExecutionMode enum values are in 1:1 correspondence with the modes defined in docs/specification.md
SubplanFailureHandler.should_stop_others() handles every defined ExecutionMode value explicitly with no implicit fallthrough
builtin/plan-subplan tool input schema is consistent with the final set of valid execution_mode values
All nox stages pass
Coverage >= 97%

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

## Metadata - **Branch**: `fix/execution-mode-dependency-ordered-undocumented` - **Commit Message**: `fix(plan): remove or document undocumented DEPENDENCY_ORDERED execution mode` - **Milestone**: v3.7.0 - **Parent Epic**: #368 ## Description The `ExecutionMode` enum in `src/cleveragents/domain/models/core/plan.py` defines three execution modes: `SEQUENTIAL`, `PARALLEL`, and `DEPENDENCY_ORDERED`. However, the specification only defines two execution modes: Sequential and Parallel. The `DEPENDENCY_ORDERED` mode is an undocumented extension not covered by the spec. ### Expected behavior (from spec) The spec (`docs/specification.md` §Child Plan Execution Modes, lines 18407–18418) defines exactly two execution modes: 1. **Sequential**: "Individual `subplan_spawn` decisions without a `subplan_parallel_spawn` wrapper execute one after another. If one fails, subsequent child plans are not started." 2. **Parallel**: "Multiple `subplan_spawn` decisions grouped under a `subplan_parallel_spawn` decision execute concurrently. If one fails, others can continue." No third mode is mentioned anywhere in the specification. ### Actual behavior The implementation adds a third mode: ```python class ExecutionMode(StrEnum): SEQUENTIAL = "sequential" # One after another, ordered by sequence PARALLEL = "parallel" # All at once (up to max_parallel) DEPENDENCY_ORDERED = "dependency_ordered" # Respect DAG dependencies ``` This mode is fully implemented in `SubplanExecutionService._execute_dependency_ordered()` with topological sort logic. It is also accepted as a valid value in `SubplanConfig.execution_mode`. ### Problems caused 1. The `DEPENDENCY_ORDERED` mode is not in the spec, so its behavior is undefined from a product perspective. 2. Users/actors that set `execution_mode: dependency_ordered` in their configs are using an undocumented feature that may change or be removed. 3. The `SubplanFailureHandler.should_stop_others()` returns `False` for `DEPENDENCY_ORDERED` (since it's not `SEQUENTIAL`), meaning failure behavior is undefined by spec. 4. The `builtin/plan-subplan` tool's input schema does not expose `dependency_ordered` as a valid merge strategy option, creating an inconsistency. ### Code locations - `src/cleveragents/domain/models/core/plan.py`, line 157: `DEPENDENCY_ORDERED = "dependency_ordered"` - `src/cleveragents/application/services/subplan_execution_service.py`, lines 338–412: `_execute_dependency_ordered()` implementation - `src/cleveragents/application/services/subplan_service.py`, lines 362–369: validation references `ExecutionMode.DEPENDENCY_ORDERED` ### Resolution options Either: - **(a)** Remove `DEPENDENCY_ORDERED` from the implementation until it is added to the spec, OR - **(b)** Update the specification to document this mode and its failure semantics ## Subtasks - [ ] Confirm with product owner whether `DEPENDENCY_ORDERED` should be removed or spec-documented - [ ] If removing: delete `ExecutionMode.DEPENDENCY_ORDERED` from `plan.py`, remove `_execute_dependency_ordered()` from `SubplanExecutionService`, and update all references in `subplan_service.py` - [ ] If documenting: add §Child Plan Execution Modes entry to `docs/specification.md` covering behavior, failure semantics, and DAG constraints - [ ] Update `SubplanFailureHandler.should_stop_others()` to handle all defined modes explicitly (no implicit fallthrough) - [ ] Update `builtin/plan-subplan` tool input schema to be consistent with the final set of valid `execution_mode` values - [ ] Write/update Behave unit tests in `features/` for the affected code paths - [ ] Ensure `nox -e typecheck` passes (Pyright) - [ ] Ensure `nox -e unit_tests` passes - [ ] Ensure `nox -e coverage_report` shows ≥ 97% coverage ## Definition of Done - [ ] `ExecutionMode` enum values are in 1:1 correspondence with the modes defined in `docs/specification.md` - [ ] `SubplanFailureHandler.should_stop_others()` handles every defined `ExecutionMode` value explicitly with no implicit fallthrough - [ ] `builtin/plan-subplan` tool input schema is consistent with the final set of valid `execution_mode` values - [ ] All nox stages pass - [ ] Coverage >= 97% --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-uat-tester

freemo added this to the v3.7.0 milestone

2026-04-03 03:49:52 +00:00

freemo added a new dependency

2026-04-03 03:50:30 +00:00

#368 Epic: Subplans & Parallelism

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

freemo referenced this issue

2026-04-03 04:01:23 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 701 — v3.7.0 #2093

freemo self-assigned this

2026-04-03 16:58:10 +00:00

freemo commented

2026-04-03 18:28:21 +00:00

Author

Owner

MoSCoW classification: Should Have

Rationale: This issue addresses a spec requirement or important quality improvement. It should be included in the milestone if possible.

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

MoSCoW classification: **Should Have** Rationale: This issue addresses a spec requirement or important quality improvement. It should be included in the milestone if possible. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner