feat(plan): implement agents plan correct with revert and append correction modes #9286

Open
opened 2026-04-14 14:03:24 +00:00 by HAL9000 · 1 comment
Owner

Metadata

  • Branch: feat/plan-correct-revert-append-modes
  • Commit: feat(plan): implement agents plan correct with revert and append correction modes
  • Milestone: v3.2.0

Background and Context

During plan execution, the LLM makes a series of decisions that are recorded in the decision tree. In practice, users often identify a decision point where the plan went in the wrong direction — either because the LLM made a suboptimal choice or because requirements have changed. Without a correction mechanism, users must either accept the flawed plan or restart from scratch.

The agents plan correct <PLAN_ID> <DECISION_ID> command addresses this by providing two correction modes:

  • --mode=revert: Discards all decisions made after the targeted decision point and re-runs the LLM from that state, effectively replaying the plan from that point forward with optional new guidance. This is a destructive operation that discards downstream work.
  • --mode=append: Adds guidance/correction text to the decision context at the targeted point without re-executing. This steers future decisions without discarding existing work, making it suitable for in-flight corrections.

Both modes integrate with the decision tree persistence layer introduced in v3.2.0 and rely on the context snapshot stored with each decision node.

Expected Behavior

  • agents plan correct <PLAN_ID> <DECISION_ID> --mode=revert [--guidance "text"]

    • Displays a confirmation prompt warning the user that all decisions after <DECISION_ID> will be discarded
    • On confirmation, prunes the decision tree at <DECISION_ID>, appends any provided guidance to the decision context, and re-executes the LLM from that state
    • The plan status transitions to correcting during re-execution and back to active or complete upon completion
    • The updated decision tree is persisted to the database
  • agents plan correct <PLAN_ID> <DECISION_ID> --mode=append [--guidance "text"]

    • Appends the provided guidance text to the decision context at <DECISION_ID> without re-executing
    • Future LLM calls that reference this decision node will include the appended guidance
    • The decision tree is updated and persisted; no re-execution occurs
    • Outputs a confirmation that guidance was appended successfully
  • Both modes:

    • Validate that <PLAN_ID> and <DECISION_ID> exist and are accessible
    • Return a structured error if the plan is in a non-correctable state (e.g., applying, applied)
    • Support --guidance "text" flag for providing correction text
    • Emit appropriate CLI output indicating what was changed

Acceptance Criteria

  • agents plan correct <PLAN_ID> <DECISION_ID> --mode=revert shows a confirmation prompt before proceeding
  • Confirming revert prunes the decision tree at the specified decision point and re-executes the LLM from that state
  • Declining the revert confirmation aborts the operation with no changes
  • agents plan correct <PLAN_ID> <DECISION_ID> --mode=append appends guidance to the decision context without re-executing
  • --guidance "text" flag is supported by both modes and correctly attached to the decision context
  • Both modes validate that <PLAN_ID> and <DECISION_ID> exist; return a clear error if not found
  • Both modes return a structured error if the plan is in a non-correctable state
  • Plan status transitions correctly during revert re-execution (correctingactive/complete)
  • Decision tree updates are persisted to the database after both modes
  • agents plan tree <PLAN_ID> reflects the corrected decision tree after either mode
  • Test coverage ≥ 97% for all new code paths

Subtasks

  • Design the CorrectionEngine class with revert() and append_guidance() methods
  • Implement decision tree pruning logic for revert mode (remove all nodes after target decision)
  • Implement guidance injection into decision context for both modes
  • Add --mode=revert|append and --guidance flags to the plan correct CLI command
  • Implement confirmation prompt for revert mode (with --yes / -y flag to skip)
  • Add plan state validation (reject corrections on applying/applied plans)
  • Wire revert re-execution into the existing LLM strategize pipeline from the target decision context
  • Update plan status transitions: activecorrectingactive/complete
  • Persist updated decision tree to the database after correction
  • Write unit tests for CorrectionEngine.revert() and CorrectionEngine.append_guidance()
  • Write integration tests for the full plan correct CLI flow (both modes)
  • Update CLI help text and command documentation
  • Verify agents plan tree renders the corrected tree correctly post-correction

Definition of Done

The issue is closed when:

  1. agents plan correct <PLAN_ID> <DECISION_ID> --mode=revert successfully re-executes the plan from the targeted decision point after user confirmation, with all downstream decisions discarded and the updated tree persisted.
  2. agents plan correct <PLAN_ID> <DECISION_ID> --mode=append successfully appends guidance to the decision context without re-executing, with the updated tree persisted.
  3. Both modes handle invalid plan/decision IDs and non-correctable plan states with clear error messages.
  4. All acceptance criteria above are checked off.
  5. Test coverage for new code is ≥ 97%.
  6. The feature is merged to the feat/plan-correct-revert-append-modes branch and passes CI.

Automated by CleverAgents Bot
Agent: new-issue-creator

## Metadata - **Branch:** `feat/plan-correct-revert-append-modes` - **Commit:** `feat(plan): implement agents plan correct with revert and append correction modes` - **Milestone:** v3.2.0 ## Background and Context During plan execution, the LLM makes a series of decisions that are recorded in the decision tree. In practice, users often identify a decision point where the plan went in the wrong direction — either because the LLM made a suboptimal choice or because requirements have changed. Without a correction mechanism, users must either accept the flawed plan or restart from scratch. The `agents plan correct <PLAN_ID> <DECISION_ID>` command addresses this by providing two correction modes: - **`--mode=revert`**: Discards all decisions made after the targeted decision point and re-runs the LLM from that state, effectively replaying the plan from that point forward with optional new guidance. This is a destructive operation that discards downstream work. - **`--mode=append`**: Adds guidance/correction text to the decision context at the targeted point without re-executing. This steers future decisions without discarding existing work, making it suitable for in-flight corrections. Both modes integrate with the decision tree persistence layer introduced in v3.2.0 and rely on the context snapshot stored with each decision node. ## Expected Behavior - `agents plan correct <PLAN_ID> <DECISION_ID> --mode=revert [--guidance "text"]` - Displays a confirmation prompt warning the user that all decisions after `<DECISION_ID>` will be discarded - On confirmation, prunes the decision tree at `<DECISION_ID>`, appends any provided guidance to the decision context, and re-executes the LLM from that state - The plan status transitions to `correcting` during re-execution and back to `active` or `complete` upon completion - The updated decision tree is persisted to the database - `agents plan correct <PLAN_ID> <DECISION_ID> --mode=append [--guidance "text"]` - Appends the provided guidance text to the decision context at `<DECISION_ID>` without re-executing - Future LLM calls that reference this decision node will include the appended guidance - The decision tree is updated and persisted; no re-execution occurs - Outputs a confirmation that guidance was appended successfully - Both modes: - Validate that `<PLAN_ID>` and `<DECISION_ID>` exist and are accessible - Return a structured error if the plan is in a non-correctable state (e.g., `applying`, `applied`) - Support `--guidance "text"` flag for providing correction text - Emit appropriate CLI output indicating what was changed ## Acceptance Criteria - [ ] `agents plan correct <PLAN_ID> <DECISION_ID> --mode=revert` shows a confirmation prompt before proceeding - [ ] Confirming revert prunes the decision tree at the specified decision point and re-executes the LLM from that state - [ ] Declining the revert confirmation aborts the operation with no changes - [ ] `agents plan correct <PLAN_ID> <DECISION_ID> --mode=append` appends guidance to the decision context without re-executing - [ ] `--guidance "text"` flag is supported by both modes and correctly attached to the decision context - [ ] Both modes validate that `<PLAN_ID>` and `<DECISION_ID>` exist; return a clear error if not found - [ ] Both modes return a structured error if the plan is in a non-correctable state - [ ] Plan status transitions correctly during revert re-execution (`correcting` → `active`/`complete`) - [ ] Decision tree updates are persisted to the database after both modes - [ ] `agents plan tree <PLAN_ID>` reflects the corrected decision tree after either mode - [ ] Test coverage ≥ 97% for all new code paths ## Subtasks - [ ] Design the `CorrectionEngine` class with `revert()` and `append_guidance()` methods - [ ] Implement decision tree pruning logic for revert mode (remove all nodes after target decision) - [ ] Implement guidance injection into decision context for both modes - [ ] Add `--mode=revert|append` and `--guidance` flags to the `plan correct` CLI command - [ ] Implement confirmation prompt for revert mode (with `--yes` / `-y` flag to skip) - [ ] Add plan state validation (reject corrections on `applying`/`applied` plans) - [ ] Wire revert re-execution into the existing LLM strategize pipeline from the target decision context - [ ] Update plan status transitions: `active` → `correcting` → `active`/`complete` - [ ] Persist updated decision tree to the database after correction - [ ] Write unit tests for `CorrectionEngine.revert()` and `CorrectionEngine.append_guidance()` - [ ] Write integration tests for the full `plan correct` CLI flow (both modes) - [ ] Update CLI help text and command documentation - [ ] Verify `agents plan tree` renders the corrected tree correctly post-correction ## Definition of Done The issue is closed when: 1. `agents plan correct <PLAN_ID> <DECISION_ID> --mode=revert` successfully re-executes the plan from the targeted decision point after user confirmation, with all downstream decisions discarded and the updated tree persisted. 2. `agents plan correct <PLAN_ID> <DECISION_ID> --mode=append` successfully appends guidance to the decision context without re-executing, with the updated tree persisted. 3. Both modes handle invalid plan/decision IDs and non-correctable plan states with clear error messages. 4. All acceptance criteria above are checked off. 5. Test coverage for new code is ≥ 97%. 6. The feature is merged to the `feat/plan-correct-revert-append-modes` branch and passes CI. --- **Automated by CleverAgents Bot** Agent: new-issue-creator
HAL9000 added this to the v3.2.0 milestone 2026-04-14 14:05:01 +00:00
Author
Owner

Triage: Verified [AUTO-OWNR-1]

Valid feature: agents plan correct with revert and append correction modes is a core M3 deliverable (v3.2.0 milestone acceptance criteria: "agents plan correct --mode=revert re-executes from the targeted decision point" and "agents plan correct --mode=append adds guidance without recomputing"). This issue provides a comprehensive specification for implementing both modes.

The CorrectionEngine design with revert() and append_guidance() methods is well-structured and aligns with the spec's requirements.

Assigning to v3.2.0 as plan correct is explicitly listed in the M3 acceptance criteria. Priority High — this is a core M3 deliverable.

MoSCoW: Must Haveagents plan correct is explicitly required by the v3.2.0 milestone acceptance criteria. The milestone cannot be considered complete without it.


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

✅ **Triage: Verified** [AUTO-OWNR-1] Valid feature: `agents plan correct` with revert and append correction modes is a core M3 deliverable (v3.2.0 milestone acceptance criteria: "`agents plan correct --mode=revert` re-executes from the targeted decision point" and "`agents plan correct --mode=append` adds guidance without recomputing"). This issue provides a comprehensive specification for implementing both modes. The `CorrectionEngine` design with `revert()` and `append_guidance()` methods is well-structured and aligns with the spec's requirements. Assigning to **v3.2.0** as `plan correct` is explicitly listed in the M3 acceptance criteria. Priority **High** — this is a core M3 deliverable. MoSCoW: **Must Have** — `agents plan correct` is explicitly required by the v3.2.0 milestone acceptance criteria. The milestone cannot be considered complete without it. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-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#9286
No description provided.