feat(subplan): execute and merge subplans #444

2026-02-25T22:23:29Z

CoreRasurae commented

2026-02-25 22:23:29 +00:00

Summary

Implements subplan execution scheduling and merge strategy infrastructure for the plan lifecycle system.

Changes

SubplanExecutionService: Scheduler supporting sequential, parallel, and dependency-ordered execution modes with configurable concurrency limits and fail-fast behavior
SubplanMergeService: Four merge strategies (git three-way, sequential apply, fail on conflict, last wins) for combining sandbox outputs from completed subplans
BDD Tests: 21 Behave scenarios covering all execution modes, merge strategies, failure handling, and retry logic
Robot Tests: 11 integration test cases for subplan execution and merge summaries
ASV Benchmarks: Performance benchmarks for scheduler overhead
Documentation: Reference documentation at docs/reference/subplans.md

Motivation

Subplan execution is a core capability for breaking down complex plans into manageable units of work. The scheduling infrastructure enables sequential, parallel, and dependency-aware execution while the merge system combines results safely using configurable strategies.

Key Design Decisions

Split into two services (SubplanExecutionService + SubplanMergeService) following SRP
Parallel execution uses asyncio.gather with semaphore-based concurrency limiting
Dependency-ordered mode performs topological sort and executes independent subplans concurrently
All services use dependency injection for testability

Closes #184

## Summary Implements subplan execution scheduling and merge strategy infrastructure for the plan lifecycle system. ### Changes - **SubplanExecutionService**: Scheduler supporting sequential, parallel, and dependency-ordered execution modes with configurable concurrency limits and fail-fast behavior - **SubplanMergeService**: Four merge strategies (git three-way, sequential apply, fail on conflict, last wins) for combining sandbox outputs from completed subplans - **BDD Tests**: 21 Behave scenarios covering all execution modes, merge strategies, failure handling, and retry logic - **Robot Tests**: 11 integration test cases for subplan execution and merge summaries - **ASV Benchmarks**: Performance benchmarks for scheduler overhead - **Documentation**: Reference documentation at `docs/reference/subplans.md` ### Motivation Subplan execution is a core capability for breaking down complex plans into manageable units of work. The scheduling infrastructure enables sequential, parallel, and dependency-aware execution while the merge system combines results safely using configurable strategies. ### Key Design Decisions - Split into two services (SubplanExecutionService + SubplanMergeService) following SRP - Parallel execution uses asyncio.gather with semaphore-based concurrency limiting - Dependency-ordered mode performs topological sort and executes independent subplans concurrently - All services use dependency injection for testability Closes #184

CoreRasurae added this to the v3.3.0 milestone 2026-02-25 22:23:53 +00:00

CoreRasurae added the

Type

Feature

label 2026-02-25 22:23:54 +00:00

CoreRasurae referenced this pull request

2026-02-25 22:24:17 +00:00

feat(subplan): execute and merge subplans #184

CoreRasurae force-pushed feature/m4-subplan-execution from cad1678bc5 to 4805e399af

2026-02-27 15:27:31 +00:00

Compare

brent.edwards reviewed 2026-02-27 21:45:48 +00:00

brent.edwards left a comment

Review Summary (commit 4805e399af97b46f3350a05b)

Scoped to the subplan execution/merge commit. The core service design is clean and the docs/tests are thorough, but there are a few behavioral gaps that will surprise callers.

CI status isn’t visible via the API on my side. Please confirm required checks per docs/development/ci-cd.md are green (lint, typecheck, security, quality, unit_tests, integration_tests, coverage, build, docker).

Findings

P1:must-fix — timeout_per_subplan_seconds is defined in SubplanConfig and documented, but never enforced in SubplanExecutionService. There’s no per‑subplan timeout in sequential or parallel modes. Implement timeouts (e.g., future.result(timeout=...) / watchdog) or remove the field/docs.

Code: src/cleveragents/application/services/subplan_execution_service.py
Model: src/cleveragents/domain/models/core/plan.py
Docs: docs/reference/subplans.md

P2:should-fix — sequential_apply is documented as “completion order,” but in parallel mode the outputs are merged in original subplan order because results are re-ordered by the input list. If completion order is intended, capture completion timestamps and sort outputs before merge.

Code: src/cleveragents/application/services/subplan_execution_service.py (_execute_parallel, execute_all)
Merge: src/cleveragents/application/services/subplan_merge_service.py
Docs: docs/reference/subplans.md

P2:should-fix — In parallel fail_fast, cancelled futures surface as CancelledError and are marked ERRORED rather than CANCELLED. This makes status reporting inconsistent with sequential mode and with the “stop others” semantics.

Code: src/cleveragents/application/services/subplan_execution_service.py

P3:should-fix — The commit message claims dependency‑ordered mode executes independent subplans concurrently, but the implementation runs them sequentially after topological sort. Either update the description/docs or implement concurrent execution for ready nodes.

Code: src/cleveragents/application/services/subplan_execution_service.py

Positive Notes

Service API and merge strategy abstraction are clean and easy to test.
Failure handling and retry logic are thoughtfully separated.
Documentation covers execution modes and merge outcomes well.

## Review Summary (commit 4805e399af97b46f3350a05b) Scoped to the subplan execution/merge commit. The core service design is clean and the docs/tests are thorough, but there are a few behavioral gaps that will surprise callers. CI status isn’t visible via the API on my side. Please confirm required checks per `docs/development/ci-cd.md` are green (lint, typecheck, security, quality, unit_tests, integration_tests, coverage, build, docker). ## Findings **P1:must-fix** — `timeout_per_subplan_seconds` is defined in `SubplanConfig` and documented, but never enforced in `SubplanExecutionService`. There’s no per‑subplan timeout in sequential or parallel modes. Implement timeouts (e.g., `future.result(timeout=...)` / watchdog) or remove the field/docs. - Code: `src/cleveragents/application/services/subplan_execution_service.py` - Model: `src/cleveragents/domain/models/core/plan.py` - Docs: `docs/reference/subplans.md` **P2:should-fix** — `sequential_apply` is documented as “completion order,” but in parallel mode the outputs are merged in **original subplan order** because results are re-ordered by the input list. If completion order is intended, capture completion timestamps and sort outputs before merge. - Code: `src/cleveragents/application/services/subplan_execution_service.py` (`_execute_parallel`, `execute_all`) - Merge: `src/cleveragents/application/services/subplan_merge_service.py` - Docs: `docs/reference/subplans.md` **P2:should-fix** — In parallel `fail_fast`, cancelled futures surface as `CancelledError` and are marked `ERRORED` rather than `CANCELLED`. This makes status reporting inconsistent with sequential mode and with the “stop others” semantics. - Code: `src/cleveragents/application/services/subplan_execution_service.py` **P3:should-fix** — The commit message claims dependency‑ordered mode executes independent subplans concurrently, but the implementation runs them sequentially after topological sort. Either update the description/docs or implement concurrent execution for ready nodes. - Code: `src/cleveragents/application/services/subplan_execution_service.py` ## Positive Notes - Service API and merge strategy abstraction are clean and easy to test. - Failure handling and retry logic are thoughtfully separated. - Documentation covers execution modes and merge outcomes well.

CoreRasurae force-pushed feature/m4-subplan-execution from 4805e399af to 1bbec743ba

2026-02-27 23:14:50 +00:00

Compare

brent.edwards approved these changes 2026-02-27 23:27:28 +00:00

Dismissed

brent.edwards left a comment

I (not an LLM) checked that the review comments were met. Great work!

freemo added the