cleveragents/cleveragents-core

Fork 3

feat(plan): implement real revert-mode re-execution from decision point #844

New issue

Closed

opened 2026-03-13 21:51:51 +00:00 by freemo · 1 comment

freemo commented

2026-03-13 21:51:51 +00:00

Owner

Background and Context

M3 (v3.2.0) acceptance criteria state: "agents plan correct --mode=revert re-executes from the targeted decision point." Per the specification (approx. lines 14907–15006, 28494–28603), the revert correction flow requires:

Resource rollback via checkpoint restoration (spec lines 28553–28561) — execute git reset --hard to restore working tree
Reasoning rollback via actor state restoration (spec line 28532, 28564) — restore the actor's context to the decision point
Resumption from the restored state (spec line 28535) — re-run strategize/execute from the decision point forward
Selective subtree recomputation — only decisions downstream of the correction point are recomputed

Currently, CorrectionService implements affected-subtree computation and decision superseding logic, but the full revert flow does NOT:

Execute real git reset (issue #822 confirms rollback is simulated)
Restore actor state to the decision point
Resume execution from the restored state

Issue #822 (bug(plan): checkpoint rollback is simulated) is assigned to v3.5.0 and covers only the git reset portion. No issue covers the reasoning rollback, state restoration, or re-execution pipeline needed for the M3 acceptance criterion.

Current Behavior

agents plan correct --mode=revert marks the targeted decision as superseded and computes the affected subtree, but does not actually restore the working tree or re-execute from the decision point. The plan state after revert is logically marked but physically unchanged.

Expected Behavior

plan correct --mode=revert --decision <id> restores the working tree to the checkpoint at the targeted decision
Actor state is restored to the context at the targeted decision
The plan automatically re-enters Strategize from the decision point
Only the affected subtree is recomputed (decisions upstream are preserved)
The new decision path is recorded in the decision tree

Acceptance Criteria

Revert mode triggers real checkpoint restoration (depends on #822 for git reset)
Actor state is restored to the decision point context
Plan re-enters Strategize automatically after revert
Only affected subtree decisions are recomputed
agents plan tree shows the original and corrected decision paths
Tests (Behave): Add scenarios for revert → re-execute → new decisions
Tests (Robot): Add integration test for full revert lifecycle
Verify coverage >=97% via nox -s coverage_report

Metadata

Type: Feature
Priority: High
MoSCoW: Must have
Points: 8
Milestone: v3.2.0

Relates to

#822 (v3.5.0 — checkpoint rollback git reset, prerequisite)
#647 (Container.resolve crash, blocks plan CLI)
M3 acceptance criterion: "agents plan correct --mode=revert re-executes from the targeted decision point"

## Background and Context M3 (v3.2.0) acceptance criteria state: *"`agents plan correct --mode=revert` re-executes from the targeted decision point."* Per the specification (approx. lines 14907–15006, 28494–28603), the revert correction flow requires: 1. **Resource rollback** via checkpoint restoration (spec lines 28553–28561) — execute `git reset --hard` to restore working tree 2. **Reasoning rollback** via actor state restoration (spec line 28532, 28564) — restore the actor's context to the decision point 3. **Resumption** from the restored state (spec line 28535) — re-run strategize/execute from the decision point forward 4. **Selective subtree recomputation** — only decisions downstream of the correction point are recomputed Currently, `CorrectionService` implements affected-subtree computation and decision superseding logic, but the full revert flow does NOT: - Execute real git reset (issue #822 confirms rollback is simulated) - Restore actor state to the decision point - Resume execution from the restored state Issue #822 (`bug(plan): checkpoint rollback is simulated`) is assigned to v3.5.0 and covers only the git reset portion. No issue covers the reasoning rollback, state restoration, or re-execution pipeline needed for the M3 acceptance criterion. ## Current Behavior `agents plan correct --mode=revert` marks the targeted decision as superseded and computes the affected subtree, but does not actually restore the working tree or re-execute from the decision point. The plan state after revert is logically marked but physically unchanged. ## Expected Behavior 1. `plan correct --mode=revert --decision <id>` restores the working tree to the checkpoint at the targeted decision 2. Actor state is restored to the context at the targeted decision 3. The plan automatically re-enters Strategize from the decision point 4. Only the affected subtree is recomputed (decisions upstream are preserved) 5. The new decision path is recorded in the decision tree ## Acceptance Criteria - [ ] Revert mode triggers real checkpoint restoration (depends on #822 for git reset) - [ ] Actor state is restored to the decision point context - [ ] Plan re-enters Strategize automatically after revert - [ ] Only affected subtree decisions are recomputed - [ ] `agents plan tree` shows the original and corrected decision paths - [ ] Tests (Behave): Add scenarios for revert → re-execute → new decisions - [ ] Tests (Robot): Add integration test for full revert lifecycle - [ ] Verify coverage >=97% via `nox -s coverage_report` ## Metadata - **Type**: Feature - **Priority**: High - **MoSCoW**: Must have - **Points**: 8 - **Milestone**: v3.2.0 ## Relates to - #822 (v3.5.0 — checkpoint rollback git reset, prerequisite) - #647 (Container.resolve crash, blocks plan CLI) - M3 acceptance criterion: "`agents plan correct --mode=revert` re-executes from the targeted decision point"

freemo added the

labels

2026-03-13 21:51:58 +00:00

freemo added this to the v3.2.0 milestone

2026-03-13 21:51:59 +00:00

CoreRasurae was assigned by freemo

2026-03-14 04:26:51 +00:00

brent.edwards added

and removed

labels

2026-03-24 19:46:28 +00:00

brent.edwards commented

2026-03-24 22:16:55 +00:00

Member

Implementation Notes

Design Decisions

1. Signal-based architecture for phase transition and actor state recovery

Rather than having CorrectionService directly manipulate plan state or LangGraph actors (which would violate separation of concerns), the enhanced execute_revert returns signal fields on CorrectionResult that downstream consumers (the CLI command handler or plan lifecycle service) use to:

Restore the LangGraph actor via actor_state_ref
Transition the plan to Strategize via phase_transition_target
Record the user intervention via user_intervention_decision_id

This keeps the correction service focused on its domain (subtree computation, checkpoint delegation, result assembly) while enabling the full revert→re-execute pipeline.

2. Graceful degradation for checkpoint restoration

The _try_checkpoint_restoration method handles three degradation scenarios:

No CheckpointService wired → skip silently (returns False)
CheckpointService raises on list_checkpoints → log warning, skip
CheckpointService raises on rollback_to_checkpoint → log warning, skip

This aligns with the spec's rollback tier model: when checkpointing is unavailable, revert still works at the "phase-level" tier (supersede decisions + re-strategize) rather than failing entirely.

3. Backward-compatible model extension

All new fields on CorrectionResult (checkpoint_restored, actor_state_ref, user_intervention_decision_id, phase_transition_target) have sensible defaults. Existing code that constructs CorrectionResult without these fields continues to work unchanged.

Key Code Locations

Model changes: cleveragents.domain.models.core.correction.CorrectionResult — 4 new fields for revert re-execution metadata (commit: pending)
Service changes: cleveragents.application.services.correction_service.CorrectionService.execute_revert — enhanced with checkpoint restoration, actor state extraction, guidance injection, and phase transition signalling
New helpers: CorrectionService._try_checkpoint_restoration and CorrectionService._extract_actor_state_ref
Dispatch update: CorrectionService.execute_correction now accepts decisions parameter and forwards to execute_revert

Test Coverage

Behave: 16 new scenarios in features/revert_re_execution.feature covering checkpoint restoration, actor state recovery, phase transition, user intervention, error paths, subtree selectivity, and dispatch integration
Robot: 7 new integration tests in robot/revert_re_execution.robot with robot/helper_revert_re_execution.py
Coverage: Overall 98% (threshold: 97%), improved from 1800 → 1793 uncovered lines

Quality Gate Results

nox -s lint: ✅ Passed
nox -s typecheck: ✅ Passed (0 errors)
nox -s unit_tests: ✅ 12376 scenarios passed (8 new), 0 failed
nox -s integration_tests: ✅ 1631 passed (6 new), 3 pre-existing failures (Container Resolve Crash #647)
nox -s e2e_tests: ✅ 37 passed
nox -s coverage_report: ✅ 98%

## Implementation Notes ### Design Decisions **1. Signal-based architecture for phase transition and actor state recovery** Rather than having `CorrectionService` directly manipulate plan state or LangGraph actors (which would violate separation of concerns), the enhanced `execute_revert` returns *signal fields* on `CorrectionResult` that downstream consumers (the CLI command handler or plan lifecycle service) use to: - Restore the LangGraph actor via `actor_state_ref` - Transition the plan to Strategize via `phase_transition_target` - Record the user intervention via `user_intervention_decision_id` This keeps the correction service focused on its domain (subtree computation, checkpoint delegation, result assembly) while enabling the full revert→re-execute pipeline. **2. Graceful degradation for checkpoint restoration** The `_try_checkpoint_restoration` method handles three degradation scenarios: - No CheckpointService wired → skip silently (returns False) - CheckpointService raises on `list_checkpoints` → log warning, skip - CheckpointService raises on `rollback_to_checkpoint` → log warning, skip This aligns with the spec's rollback tier model: when checkpointing is unavailable, revert still works at the "phase-level" tier (supersede decisions + re-strategize) rather than failing entirely. **3. Backward-compatible model extension** All new fields on `CorrectionResult` (`checkpoint_restored`, `actor_state_ref`, `user_intervention_decision_id`, `phase_transition_target`) have sensible defaults. Existing code that constructs `CorrectionResult` without these fields continues to work unchanged. ### Key Code Locations - **Model changes**: `cleveragents.domain.models.core.correction.CorrectionResult` — 4 new fields for revert re-execution metadata (commit: pending) - **Service changes**: `cleveragents.application.services.correction_service.CorrectionService.execute_revert` — enhanced with checkpoint restoration, actor state extraction, guidance injection, and phase transition signalling - **New helpers**: `CorrectionService._try_checkpoint_restoration` and `CorrectionService._extract_actor_state_ref` - **Dispatch update**: `CorrectionService.execute_correction` now accepts `decisions` parameter and forwards to `execute_revert` ### Test Coverage - **Behave**: 16 new scenarios in `features/revert_re_execution.feature` covering checkpoint restoration, actor state recovery, phase transition, user intervention, error paths, subtree selectivity, and dispatch integration - **Robot**: 7 new integration tests in `robot/revert_re_execution.robot` with `robot/helper_revert_re_execution.py` - **Coverage**: Overall 98% (threshold: 97%), improved from 1800 → 1793 uncovered lines ### Quality Gate Results - `nox -s lint`: ✅ Passed - `nox -s typecheck`: ✅ Passed (0 errors) - `nox -s unit_tests`: ✅ 12376 scenarios passed (8 new), 0 failed - `nox -s integration_tests`: ✅ 1631 passed (6 new), 3 pre-existing failures (Container Resolve Crash #647) - `nox -s e2e_tests`: ✅ 37 passed - `nox -s coverage_report`: ✅ 98%

brent.edwards referenced this issue from a commit

2026-03-24 22:17:22 +00:00

feat(plan): implement real revert-mode re-execution from decision point

~~brent.edwards referenced this issue 2026-03-24 22:17:33 +00:00~~

feat(plan): implement real revert-mode re-execution from decision point #1153

brent.edwards added a new dependency

2026-03-24 22:18:08 +00:00

#1153 feat(plan): implement real revert-mode re-execution from decision point

brent.edwards added

State

In Review

and removed