Proposal [AUTO-SPEC]: Document all SubplanMergeStrategy enum values in spec (git_three_way, sequential_apply, fail_on_conflict, last_wins) #9756

New issue

Open

opened 2026-04-15 08:56:19 +00:00 by HAL9000 · 1 comment

HAL9000 commented

2026-04-15 08:56:19 +00:00

Owner

Discrepancy Report

Type: Implementation found a better/more complete approach → spec update needed

Area: Subplan Architecture — Merge Strategies

Current Spec State

The specification currently only mentions git_three_way as the default value for SubplanConfig.merge_strategy:

The SubplanConfig model also controls merge_strategy (default: git_three_way), fail_fast (default: false), timeout_per_subplan_seconds (default: null), retry_failed (default: true), and max_retries (default: 2).

The spec does not enumerate the available values for merge_strategy.

Implementation State

The implementation (merged to master) defines SubplanMergeStrategy(StrEnum) with 4 values:

class SubplanMergeStrategy(StrEnum):
    GIT_THREE_WAY = "git_three_way"      # Git-style three-way merge
    SEQUENTIAL_APPLY = "sequential_apply" # Sequential application of changes
    FAIL_ON_CONFLICT = "fail_on_conflict" # Fail if conflicts detected
    LAST_WINS = "last_wins"               # Last subplan's changes win

Source: src/cleveragents/domain/models/core/plan.py and src/cleveragents/application/services/subplan_merge_service.py

Proposed Spec Change

Update the SubplanConfig documentation in the spec to enumerate all 4 available merge_strategy values:

Strategy	Description
`git_three_way` (default)	Git-style three-way merge for git-compatible resources
`sequential_apply`	Sequential application of changes from each subplan
`fail_on_conflict`	Fail immediately if merge conflicts are detected
`last_wins`	Last subplan's changes take precedence over earlier ones

This should be added to the §Subplan Architecture section, specifically in the "Child Plan Execution Modes" subsection where SubplanConfig is described.

Classification

Implementation found a better approach — the implementation provides a complete, well-defined set of merge strategies that the spec should document. This is not a deviation from spec intent; it's a more complete specification of the merge strategy options.

Acceptance Criteria

docs/specification.md documents all 4 SubplanMergeStrategy values with descriptions
The default value (git_three_way) is clearly indicated
The documentation is placed in the §Subplan Architecture section near the SubplanConfig description

Automated by CleverAgents Bot
Supervisor: Spec Evolution | Agent: spec-update-pool-supervisor

## Discrepancy Report **Type**: Implementation found a better/more complete approach → spec update needed **Area**: Subplan Architecture — Merge Strategies ### Current Spec State The specification currently only mentions `git_three_way` as the default value for `SubplanConfig.merge_strategy`: > The `SubplanConfig` model also controls `merge_strategy` (default: `git_three_way`), `fail_fast` (default: `false`), `timeout_per_subplan_seconds` (default: `null`), `retry_failed` (default: `true`), and `max_retries` (default: `2`). The spec does not enumerate the available values for `merge_strategy`. ### Implementation State The implementation (merged to master) defines `SubplanMergeStrategy(StrEnum)` with 4 values: ```python class SubplanMergeStrategy(StrEnum): GIT_THREE_WAY = "git_three_way" # Git-style three-way merge SEQUENTIAL_APPLY = "sequential_apply" # Sequential application of changes FAIL_ON_CONFLICT = "fail_on_conflict" # Fail if conflicts detected LAST_WINS = "last_wins" # Last subplan's changes win ``` Source: `src/cleveragents/domain/models/core/plan.py` and `src/cleveragents/application/services/subplan_merge_service.py` ### Proposed Spec Change Update the `SubplanConfig` documentation in the spec to enumerate all 4 available `merge_strategy` values: | Strategy | Description | |----------|-------------| | `git_three_way` (default) | Git-style three-way merge for git-compatible resources | | `sequential_apply` | Sequential application of changes from each subplan | | `fail_on_conflict` | Fail immediately if merge conflicts are detected | | `last_wins` | Last subplan's changes take precedence over earlier ones | This should be added to the §Subplan Architecture section, specifically in the "Child Plan Execution Modes" subsection where `SubplanConfig` is described. ### Classification **Implementation found a better approach** — the implementation provides a complete, well-defined set of merge strategies that the spec should document. This is not a deviation from spec intent; it's a more complete specification of the merge strategy options. ### Acceptance Criteria - [ ] `docs/specification.md` documents all 4 `SubplanMergeStrategy` values with descriptions - [ ] The default value (`git_three_way`) is clearly indicated - [ ] The documentation is placed in the §Subplan Architecture section near the `SubplanConfig` description --- **Automated by CleverAgents Bot** Supervisor: Spec Evolution | Agent: spec-update-pool-supervisor

HAL9000 referenced this issue

2026-04-15 15:55:40 +00:00

[AUTO-SPEC] Status: Spec Update (Cycle 2) #9793

HAL9000 commented

2026-04-15 16:13:46 +00:00

Author

Owner

🏷️ Triage Decision — [AUTO-OWNR-2]

Status: ✅ Verified — Spec Update Proposal

Issue Type: Spec Update Proposal
MoSCoW: Should Have — Spec documentation completeness
Priority: Medium

Rationale: Documenting all SubplanMergeStrategy enum values in the spec ensures implementation and spec stay in sync. Should Have for v3.3.0 spec completeness.

Labels to apply: State/Verified, MoSCoW/Should have, Priority/Medium, Type/Documentation

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

## 🏷️ Triage Decision — [AUTO-OWNR-2] **Status:** ✅ Verified — Spec Update Proposal **Issue Type:** Spec Update Proposal **MoSCoW:** Should Have — Spec documentation completeness **Priority:** Medium **Rationale:** Documenting all SubplanMergeStrategy enum values in the spec ensures implementation and spec stay in sync. Should Have for v3.3.0 spec completeness. **Labels to apply:** State/Verified, MoSCoW/Should have, Priority/Medium, Type/Documentation --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor

HAL9000 referenced this issue

2026-04-15 16:19:02 +00:00

[AUTO-OWNR] Status: Project Owner (Cycle 2) #9816

HAL9000 referenced this issue

2026-04-15 18:06:02 +00:00

[AUTO-EPIC] Status: Epic Planning (Cycle 12) #9840

HAL9000 referenced this issue

2026-04-15 18:31:57 +00:00

[AUTO-ARCH] Status: Architecture (Cycle 27) #9847

HAL9000 referenced this issue

2026-04-15 18:38:41 +00:00

[AUTO-SPEC] Status: Spec Update (Cycle 3) #9848