Epic: Three-Way Merge & Result Integration (v3.3.0) #8491

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

Metadata

  • Commit message: feat(plans): implement three-way merge strategy for subplan result integration
  • Branch name: feat/v3.3.0-three-way-merge-result-integration

Background and Context

As part of the v3.3.0 milestone (M4: Corrections + Subplans + Checkpoints), once subplans complete execution (see Epic: Subplan Spawning & Parallel Execution), their results must be merged back into the parent plan's state. This requires a robust merge strategy that can handle concurrent modifications from multiple subplans.

This Epic covers the implementation of a three-way merge engine for subplan result integration. The three-way merge uses the common ancestor (the parent plan state at spawn time), the parent plan's current state, and each subplan's result state to produce a merged output. Non-conflicting changes are applied automatically. Conflicting changes are detected and surfaced to the user for manual resolution.

This Epic BLOCKS Legendary #8486.

Expected Behavior

  • After subplan completion, the merge engine is invoked with: (1) ancestor state, (2) parent current state, (3) subplan result state.
  • Non-conflicting changes from the subplan are automatically applied to the parent plan state.
  • Conflicting changes (where both parent and subplan modified the same field/resource) are detected.
  • Conflicts are surfaced to the user with clear context: what changed in the parent, what changed in the subplan, and what the ancestor value was.
  • The user can resolve conflicts interactively or via a resolution strategy config.
  • Merge results are validated before being committed to the parent plan state.
  • Multiple subplan results can be merged sequentially or in a defined order.

Acceptance Criteria

  • Three-way merge engine implemented and integrated with subplan result flow
  • Non-conflicting changes from subplans are automatically applied
  • Conflicting changes are detected correctly
  • Conflicts are surfaced to the user with ancestor/parent/subplan context
  • Merge strategy is configurable (e.g., prefer-parent, prefer-subplan, manual)
  • Merge results are validated before committing to parent plan state
  • Multiple subplan results can be merged in sequence
  • Unit tests cover non-conflict, conflict detection, and resolution scenarios
  • Integration tests cover end-to-end subplan spawn → merge flow
  • Test coverage >= 97% for all new modules in this Epic

Subtasks

  • Design three-way merge algorithm and data model (ancestor, ours, theirs)
  • Implement ThreeWayMergeEngine with non-conflict auto-apply logic
  • Implement conflict detection for overlapping field/resource modifications
  • Implement conflict surfacing interface (structured conflict report for user)
  • Implement configurable merge strategy (prefer-parent, prefer-subplan, manual)
  • Integrate merge engine into subplan result collection step
  • Implement merge result validation before parent state commit
  • Support sequential merging of multiple subplan results
  • Write unit tests for merge engine (no conflict, conflict, resolution)
  • Write integration tests for full spawn → execute → merge flow

Child Issues / Child Epics

Feature issues will be linked here as they are created.

  • Feature: ThreeWayMergeEngine implementation — TBD
  • Feature: Conflict detection and user surfacing — TBD
  • Feature: Configurable merge strategy — TBD

Definition of Done

This Epic is closed when:

  1. All subtasks above are complete and checked off.
  2. All Acceptance Criteria are verified.
  3. Test coverage >= 97% for all new modules.
  4. The merge engine is confirmed as integrated with the Subplan Spawning Epic output.
  5. This Epic is confirmed as unblocking Legendary #8486.

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

## Metadata - **Commit message**: `feat(plans): implement three-way merge strategy for subplan result integration` - **Branch name**: `feat/v3.3.0-three-way-merge-result-integration` ## Background and Context As part of the v3.3.0 milestone (M4: Corrections + Subplans + Checkpoints), once subplans complete execution (see Epic: Subplan Spawning & Parallel Execution), their results must be merged back into the parent plan's state. This requires a robust merge strategy that can handle concurrent modifications from multiple subplans. This Epic covers the implementation of a three-way merge engine for subplan result integration. The three-way merge uses the common ancestor (the parent plan state at spawn time), the parent plan's current state, and each subplan's result state to produce a merged output. Non-conflicting changes are applied automatically. Conflicting changes are detected and surfaced to the user for manual resolution. **This Epic BLOCKS Legendary #8486.** ## Expected Behavior - After subplan completion, the merge engine is invoked with: (1) ancestor state, (2) parent current state, (3) subplan result state. - Non-conflicting changes from the subplan are automatically applied to the parent plan state. - Conflicting changes (where both parent and subplan modified the same field/resource) are detected. - Conflicts are surfaced to the user with clear context: what changed in the parent, what changed in the subplan, and what the ancestor value was. - The user can resolve conflicts interactively or via a resolution strategy config. - Merge results are validated before being committed to the parent plan state. - Multiple subplan results can be merged sequentially or in a defined order. ## Acceptance Criteria - [ ] Three-way merge engine implemented and integrated with subplan result flow - [ ] Non-conflicting changes from subplans are automatically applied - [ ] Conflicting changes are detected correctly - [ ] Conflicts are surfaced to the user with ancestor/parent/subplan context - [ ] Merge strategy is configurable (e.g., prefer-parent, prefer-subplan, manual) - [ ] Merge results are validated before committing to parent plan state - [ ] Multiple subplan results can be merged in sequence - [ ] Unit tests cover non-conflict, conflict detection, and resolution scenarios - [ ] Integration tests cover end-to-end subplan spawn → merge flow - [ ] Test coverage >= 97% for all new modules in this Epic ## Subtasks - [ ] Design three-way merge algorithm and data model (ancestor, ours, theirs) - [ ] Implement `ThreeWayMergeEngine` with non-conflict auto-apply logic - [ ] Implement conflict detection for overlapping field/resource modifications - [ ] Implement conflict surfacing interface (structured conflict report for user) - [ ] Implement configurable merge strategy (prefer-parent, prefer-subplan, manual) - [ ] Integrate merge engine into subplan result collection step - [ ] Implement merge result validation before parent state commit - [ ] Support sequential merging of multiple subplan results - [ ] Write unit tests for merge engine (no conflict, conflict, resolution) - [ ] Write integration tests for full spawn → execute → merge flow ## Child Issues / Child Epics > Feature issues will be linked here as they are created. - [ ] Feature: ThreeWayMergeEngine implementation — _TBD_ - [ ] Feature: Conflict detection and user surfacing — _TBD_ - [ ] Feature: Configurable merge strategy — _TBD_ ## Definition of Done This Epic is closed when: 1. All subtasks above are complete and checked off. 2. All Acceptance Criteria are verified. 3. Test coverage >= 97% for all new modules. 4. The merge engine is confirmed as integrated with the Subplan Spawning Epic output. 5. This Epic is confirmed as unblocking Legendary #8486. --- **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:32 +00:00
Author
Owner

[AUTO-OWNR-3] Triage Decision

Status: Verified

MoSCoW: Must Have
Priority: High

Rationale: Three-way merge is explicitly required by the v3.3.0 milestone acceptance criteria: "Three-way merge combines non-conflicting changes; conflicts surfaced to user." This Epic is blocked by #8489 (Subplan Spawning) and directly blocks the Legendary #8486. Priority/High is appropriate — this is required for v3.3.0 but is sequentially dependent on the subplan spawning work completing first, making it slightly lower urgency than the Critical-priority spawning Epic.

Next Steps: This Epic is blocked until #8489 (Subplan Spawning & Parallel Execution) is complete. Begin design of the ThreeWayMergeEngine data model (ancestor/ours/theirs) in parallel with #8489 implementation. Conflict detection and user-facing surfacing interface should be designed early to avoid rework.


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

## [AUTO-OWNR-3] Triage Decision **Status**: ✅ Verified **MoSCoW**: Must Have **Priority**: High **Rationale**: Three-way merge is explicitly required by the v3.3.0 milestone acceptance criteria: "Three-way merge combines non-conflicting changes; conflicts surfaced to user." This Epic is blocked by #8489 (Subplan Spawning) and directly blocks the Legendary #8486. Priority/High is appropriate — this is required for v3.3.0 but is sequentially dependent on the subplan spawning work completing first, making it slightly lower urgency than the Critical-priority spawning Epic. **Next Steps**: This Epic is blocked until #8489 (Subplan Spawning & Parallel Execution) is complete. Begin design of the `ThreeWayMergeEngine` data model (ancestor/ours/theirs) in parallel with #8489 implementation. Conflict detection and user-facing surfacing interface should be designed early to avoid rework. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor
Author
Owner

🧩 Child Issues Created for Epic #8491

The following child implementation issues have been created for this Epic. Each child issue blocks this Epic and is assigned to milestone v3.3.0.

# Issue Labels
1 #8552feat(plans): implement three-way merge strategy for subplan result integration Type/Feature · Priority/High · MoSCoW/Must have · State/Verified
2 #8553feat(plans): implement merge conflict surfacing and user resolution flow Type/Feature · Priority/High · MoSCoW/Must have · State/Verified
3 #8554feat(plans): implement subplan result collection and parent plan state update Type/Feature · Priority/High · MoSCoW/Must have · State/Verified

All three issues follow the CONTRIBUTING.md format with Metadata, Background and Context, Expected Behavior, Acceptance Criteria, Subtasks, and Definition of Done sections.


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

## 🧩 Child Issues Created for Epic #8491 The following child implementation issues have been created for this Epic. Each child issue blocks this Epic and is assigned to milestone **v3.3.0**. | # | Issue | Labels | |---|---|---| | 1 | #8552 — `feat(plans): implement three-way merge strategy for subplan result integration` | Type/Feature · Priority/High · MoSCoW/Must have · State/Verified | | 2 | #8553 — `feat(plans): implement merge conflict surfacing and user resolution flow` | Type/Feature · Priority/High · MoSCoW/Must have · State/Verified | | 3 | #8554 — `feat(plans): implement subplan result collection and parent plan state update` | Type/Feature · Priority/High · MoSCoW/Must have · State/Verified | All three issues follow the CONTRIBUTING.md format with Metadata, Background and Context, Expected Behavior, Acceptance Criteria, Subtasks, and Definition of Done sections. --- **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#8491
No description provided.