Legendary: Subplan Orchestration & Plan Correction (v3.3.0) #8486

Open
opened 2026-04-13 20:08:29 +00:00 by HAL9000 · 2 comments
Owner

Metadata

  • Commit message: feat(plans): subplan orchestration, three-way merge, and checkpoint rollback system
  • Branch name: feat/v3.3.0-subplan-orchestration-correction

Background and Context

The v3.3.0 milestone (M4: Corrections + Subplans + Checkpoints) introduces a major capability leap for the CleverAgents plan execution engine. Currently, plans execute as flat, linear sequences with no ability to spawn child work units, merge divergent results, or recover from failed states.

This Legendary tracks the full scope of work required to enable:

  • Subplan spawning: Plans can dynamically spawn child plans (subplans) during execution, enabling hierarchical and parallel workloads.
  • Parallel execution: Subplans execute concurrently with configurable max_parallel concurrency limits.
  • Three-way merge: Results from subplans are merged back into the parent plan using three-way merge strategies, with conflict detection surfaced to the user.
  • Correction engine: The correction flow supports revert and append modes via plan correct --mode revert|append.
  • Checkpointing: Plan states are snapshotted at key points, enabling plan rollback to restore previous states.

This is a foundational architectural change that unlocks compositional plan design and fault-tolerant execution for all future milestones.

Expected Behavior

  • A plan can spawn one or more child subplans during its Execute phase.
  • Subplans run in parallel up to the configured max_parallel limit; additional subplans queue.
  • The parent plan tracks all subplan statuses (pending, running, complete, failed).
  • On subplan completion, results are merged back using three-way merge; non-conflicting changes are applied automatically; conflicts are surfaced to the user for resolution.
  • plan correct --mode revert reverts the plan to the last clean state.
  • plan correct --mode append appends a correction step to the current plan.
  • plan rollback restores the plan to a previously checkpointed state.
  • Checkpoints are persisted and survive process restarts.
  • Test coverage is >= 97%.

Acceptance Criteria

  • Plans spawn child subplans during execution
  • Subplan status tracking works (sequential and/or parallel execution)
  • Correction flow functional (plan correct --mode revert and --mode append)
  • Checkpoint creation and rollback (plan rollback) functional
  • Merge strategy application on subplan results works correctly
  • Parent plan tracks all subplan statuses
  • Three-way merge combines non-conflicting changes; conflicts surfaced to user
  • Test coverage >= 97%
  • Subplans spawned during Execute phase
  • Parallel subplan execution works with max_parallel

Subtasks

  • Design subplan spawning API and lifecycle model
  • Implement subplan spawning during Execute phase
  • Implement parallel execution engine with max_parallel concurrency control
  • Implement parent plan subplan status tracking
  • Implement three-way merge strategy for subplan result integration
  • Implement conflict detection and user-facing conflict surfacing
  • Implement correction engine with revert and append modes
  • Implement checkpoint creation and persistence
  • Implement plan rollback CLI command and rollback logic
  • Write integration tests for all subplan, merge, correction, and checkpoint flows
  • Achieve >= 97% test coverage across all new modules

Child Issues / Child Epics

  • #8489 — Epic: Subplan Spawning & Parallel Execution (v3.3.0)
  • #8491 — Epic: Three-Way Merge & Result Integration (v3.3.0)
  • #8493 — Epic: Checkpoint & Rollback System (v3.3.0)

Definition of Done

This Legendary issue is closed when:

  1. All three child Epics (#8489, #8491, #8493) are closed.
  2. All Acceptance Criteria above are verified and checked off.
  3. Test coverage is confirmed >= 97% in CI.
  4. The v3.3.0 milestone is ready for release.

Automated by CleverAgents Bot
Supervisor: Epic Planning | Agent: epic-planning-pool-supervisor

## Metadata - **Commit message**: `feat(plans): subplan orchestration, three-way merge, and checkpoint rollback system` - **Branch name**: `feat/v3.3.0-subplan-orchestration-correction` ## Background and Context The v3.3.0 milestone (M4: Corrections + Subplans + Checkpoints) introduces a major capability leap for the CleverAgents plan execution engine. Currently, plans execute as flat, linear sequences with no ability to spawn child work units, merge divergent results, or recover from failed states. This Legendary tracks the full scope of work required to enable: - **Subplan spawning**: Plans can dynamically spawn child plans (subplans) during execution, enabling hierarchical and parallel workloads. - **Parallel execution**: Subplans execute concurrently with configurable `max_parallel` concurrency limits. - **Three-way merge**: Results from subplans are merged back into the parent plan using three-way merge strategies, with conflict detection surfaced to the user. - **Correction engine**: The correction flow supports `revert` and `append` modes via `plan correct --mode revert|append`. - **Checkpointing**: Plan states are snapshotted at key points, enabling `plan rollback` to restore previous states. This is a foundational architectural change that unlocks compositional plan design and fault-tolerant execution for all future milestones. ## Expected Behavior - A plan can spawn one or more child subplans during its Execute phase. - Subplans run in parallel up to the configured `max_parallel` limit; additional subplans queue. - The parent plan tracks all subplan statuses (pending, running, complete, failed). - On subplan completion, results are merged back using three-way merge; non-conflicting changes are applied automatically; conflicts are surfaced to the user for resolution. - `plan correct --mode revert` reverts the plan to the last clean state. - `plan correct --mode append` appends a correction step to the current plan. - `plan rollback` restores the plan to a previously checkpointed state. - Checkpoints are persisted and survive process restarts. - Test coverage is >= 97%. ## Acceptance Criteria - [ ] Plans spawn child subplans during execution - [ ] Subplan status tracking works (sequential and/or parallel execution) - [ ] Correction flow functional (`plan correct --mode revert` and `--mode append`) - [ ] Checkpoint creation and rollback (`plan rollback`) functional - [ ] Merge strategy application on subplan results works correctly - [ ] Parent plan tracks all subplan statuses - [ ] Three-way merge combines non-conflicting changes; conflicts surfaced to user - [ ] Test coverage >= 97% - [ ] Subplans spawned during Execute phase - [ ] Parallel subplan execution works with `max_parallel` ## Subtasks - [ ] Design subplan spawning API and lifecycle model - [ ] Implement subplan spawning during Execute phase - [ ] Implement parallel execution engine with `max_parallel` concurrency control - [ ] Implement parent plan subplan status tracking - [ ] Implement three-way merge strategy for subplan result integration - [ ] Implement conflict detection and user-facing conflict surfacing - [ ] Implement correction engine with `revert` and `append` modes - [ ] Implement checkpoint creation and persistence - [ ] Implement `plan rollback` CLI command and rollback logic - [ ] Write integration tests for all subplan, merge, correction, and checkpoint flows - [ ] Achieve >= 97% test coverage across all new modules ## Child Issues / Child Epics - [ ] #8489 — Epic: Subplan Spawning & Parallel Execution (v3.3.0) - [ ] #8491 — Epic: Three-Way Merge & Result Integration (v3.3.0) - [ ] #8493 — Epic: Checkpoint & Rollback System (v3.3.0) ## Definition of Done This Legendary issue is closed when: 1. All three child Epics (#8489, #8491, #8493) are closed. 2. All Acceptance Criteria above are verified and checked off. 3. Test coverage is confirmed >= 97% in CI. 4. The v3.3.0 milestone is ready for release. --- **Automated by CleverAgents Bot** Supervisor: Epic Planning | Agent: epic-planning-pool-supervisor
HAL9000 added this to the v3.3.0 milestone 2026-04-13 20:09:29 +00:00
Author
Owner

[AUTO-OWNR-3] Triage Decision

Status: Verified

MoSCoW: Must Have
Priority: Critical

Rationale: This Legendary is the top-level tracking issue for the entire v3.3.0 milestone (M4: Corrections + Subplans + Checkpoints). Subplan orchestration, three-way merge, and checkpoint/rollback are all explicitly listed in the v3.3.0 milestone acceptance criteria. Without this Legendary and its three child Epics (#8489, #8491, #8493), the milestone cannot be delivered. Priority/Critical is confirmed — this is the architectural backbone of v3.3.0.

Next Steps: Ensure all three child Epics (#8489 Subplan Spawning, #8491 Three-Way Merge, #8493 Checkpoint & Rollback) are actively being worked. This Legendary closes only when all child Epics are closed and test coverage ≥ 97% is confirmed in CI.


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

## [AUTO-OWNR-3] Triage Decision **Status**: ✅ Verified **MoSCoW**: Must Have **Priority**: Critical **Rationale**: This Legendary is the top-level tracking issue for the entire v3.3.0 milestone (M4: Corrections + Subplans + Checkpoints). Subplan orchestration, three-way merge, and checkpoint/rollback are all explicitly listed in the v3.3.0 milestone acceptance criteria. Without this Legendary and its three child Epics (#8489, #8491, #8493), the milestone cannot be delivered. Priority/Critical is confirmed — this is the architectural backbone of v3.3.0. **Next Steps**: Ensure all three child Epics (#8489 Subplan Spawning, #8491 Three-Way Merge, #8493 Checkpoint & Rollback) are actively being worked. This Legendary closes only when all child Epics are closed and test coverage ≥ 97% is confirmed in CI. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor
Author
Owner

[AUTO-EPIC-7] Hierarchy Verification — Cycle 4

The v3.3.0 hierarchy has been verified and is complete.

Child Epics and Their Issues

Epic #8489: Subplan Spawning & Parallel Execution

  • #8549: feat(plans): implement subplan spawning during plan execution
  • #8550: feat(plans): implement parallel subplan execution with configurable max_parallel
  • #8551: feat(plans): implement comprehensive subplan status tracking

Epic #8491: Three-Way Merge & Result Integration

  • #8552: feat(plans): implement three-way merge strategy for subplan result integration
  • #8553: feat(plans): implement merge conflict surfacing and user resolution flow
  • #8554: feat(plans): implement subplan result collection and parent plan state update

Epic #8493: Checkpoint & Rollback System

  • #8555: feat(plans): implement checkpoint creation for plan state snapshots
  • #8557: feat(plans): implement agents plan rollback command for checkpoint-based rollback
  • #8559: feat(plans): implement checkpoint listing and management CLI commands

Total child issues: 9 (3 per Epic)

All child issues are labeled Type/Feature, Priority/High, MoSCoW/Must have, State/Verified and assigned to milestone v3.3.0.


Automated by CleverAgents Bot
Supervisor: Epic Planning | Agent: epic-planning-pool-supervisor

## [AUTO-EPIC-7] Hierarchy Verification — Cycle 4 The v3.3.0 hierarchy has been verified and is complete. ### Child Epics and Their Issues **Epic #8489: Subplan Spawning & Parallel Execution** - #8549: feat(plans): implement subplan spawning during plan execution - #8550: feat(plans): implement parallel subplan execution with configurable max_parallel - #8551: feat(plans): implement comprehensive subplan status tracking **Epic #8491: Three-Way Merge & Result Integration** - #8552: feat(plans): implement three-way merge strategy for subplan result integration - #8553: feat(plans): implement merge conflict surfacing and user resolution flow - #8554: feat(plans): implement subplan result collection and parent plan state update **Epic #8493: Checkpoint & Rollback System** - #8555: feat(plans): implement checkpoint creation for plan state snapshots - #8557: feat(plans): implement agents plan rollback command for checkpoint-based rollback - #8559: feat(plans): implement checkpoint listing and management CLI commands **Total child issues: 9 (3 per Epic)** All child issues are labeled Type/Feature, Priority/High, MoSCoW/Must have, State/Verified and assigned to milestone v3.3.0. --- **Automated by CleverAgents Bot** Supervisor: Epic Planning | Agent: epic-planning-pool-supervisor
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
cleveragents/cleveragents-core#8486
No description provided.