Legendary: Decision Recording & Plan Management (v3.2.0) #8475

Closed
opened 2026-04-13 20:05:17 +00:00 by HAL9000 · 3 comments
Owner

Metadata

  • Commit message: feat(decisions): implement decision recording, plan management, invariants, and plan correction for v3.2.0
  • Branch name: feat/v3.2.0-decision-recording-plan-management

Background and Context

The v3.2.0 milestone (M3: Decisions + Validations + Invariants) introduces a foundational capability: recording decisions made during the Strategize and Execute phases, persisting them to the database, and providing users with rich CLI tooling to inspect, manage, and correct those decisions.

Currently, the agent system executes plans without a persistent audit trail of the reasoning behind each decision. This makes it impossible to review why a particular path was chosen, enforce constraints (invariants) across planning sessions, or surgically correct a bad decision without re-running the entire plan from scratch.

This Legendary issue tracks the full scope of work across three child Epics that together deliver the complete Decision Recording & Plan Management system.

Expected Behavior

When complete, the system will:

  • Record every decision made during Strategize and Execute phases with full context snapshots
  • Persist decisions to the database for durable audit trails
  • Allow users to visualize the decision tree via agents plan tree
  • Allow users to inspect individual decisions (including alternatives considered) via agents plan explain
  • Allow users to create, list, and remove invariants via agents invariant add/list/remove
  • Enforce invariants automatically during the Strategize phase
  • Allow users to correct decisions via agents plan correct --mode=revert (re-execute from a decision point) or agents plan correct --mode=append (add guidance without recomputing)
  • Validate outputs flexibly — checking structural components rather than exact character matching
  • Achieve >= 97% test coverage across all new functionality

Acceptance Criteria

  • Decisions are recorded during Strategize with full context snapshots
  • Decisions are recorded during Execute with full context snapshots
  • Decision data is persisted to the database
  • agents plan tree renders the decision tree correctly
  • agents plan explain shows decision details including alternatives considered
  • agents invariant add creates invariants and persists them
  • agents invariant list displays all active invariants
  • agents invariant remove deletes a specified invariant
  • Invariants are enforced during the Strategize phase
  • agents plan correct --mode=revert re-executes from the targeted decision point
  • agents plan correct --mode=append adds guidance without recomputing the subtree
  • Output validation checks structural components, not exact character matching
  • Test coverage >= 97% across all new v3.2.0 functionality

Subtasks

  • [Epic #8477] Decision Recording & Persistence — record decisions, persist to DB, implement plan tree and plan explain
  • [Epic #8480] Invariant Management System — invariant add/list/remove, enforcement during Strategize, persistence
  • [Epic #8481] Plan Correction Engine — plan correct --mode=revert|append, selective subtree recomputation, output validation flexibility

Child Issues / Child Epics

# Title Priority Status
#8477 Epic: Decision Recording & Persistence (v3.2.0) Critical 🔲 Open
#8480 Epic: Invariant Management System (v3.2.0) High 🔲 Open
#8481 Epic: Plan Correction Engine (v3.2.0) High 🔲 Open

All three child Epics block this Legendary. This issue should remain open until all Epics are closed and all Acceptance Criteria are verified.

Definition of Done

This Legendary issue should be closed when:

  1. All three child Epics (#8477, #8480, #8481) are closed
  2. All Acceptance Criteria above are verified and checked off
  3. Test coverage >= 97% is confirmed by CI
  4. The feature has passed UAT review
  5. All related PRs are merged to the main branch

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

## Metadata - **Commit message**: `feat(decisions): implement decision recording, plan management, invariants, and plan correction for v3.2.0` - **Branch name**: `feat/v3.2.0-decision-recording-plan-management` ## Background and Context The v3.2.0 milestone (M3: Decisions + Validations + Invariants) introduces a foundational capability: recording decisions made during the Strategize and Execute phases, persisting them to the database, and providing users with rich CLI tooling to inspect, manage, and correct those decisions. Currently, the agent system executes plans without a persistent audit trail of the reasoning behind each decision. This makes it impossible to review why a particular path was chosen, enforce constraints (invariants) across planning sessions, or surgically correct a bad decision without re-running the entire plan from scratch. This Legendary issue tracks the full scope of work across three child Epics that together deliver the complete Decision Recording & Plan Management system. ## Expected Behavior When complete, the system will: - Record every decision made during Strategize and Execute phases with full context snapshots - Persist decisions to the database for durable audit trails - Allow users to visualize the decision tree via `agents plan tree` - Allow users to inspect individual decisions (including alternatives considered) via `agents plan explain` - Allow users to create, list, and remove invariants via `agents invariant add/list/remove` - Enforce invariants automatically during the Strategize phase - Allow users to correct decisions via `agents plan correct --mode=revert` (re-execute from a decision point) or `agents plan correct --mode=append` (add guidance without recomputing) - Validate outputs flexibly — checking structural components rather than exact character matching - Achieve >= 97% test coverage across all new functionality ## Acceptance Criteria - [ ] Decisions are recorded during Strategize with full context snapshots - [ ] Decisions are recorded during Execute with full context snapshots - [ ] Decision data is persisted to the database - [ ] `agents plan tree` renders the decision tree correctly - [ ] `agents plan explain` shows decision details including alternatives considered - [ ] `agents invariant add` creates invariants and persists them - [ ] `agents invariant list` displays all active invariants - [ ] `agents invariant remove` deletes a specified invariant - [ ] Invariants are enforced during the Strategize phase - [ ] `agents plan correct --mode=revert` re-executes from the targeted decision point - [ ] `agents plan correct --mode=append` adds guidance without recomputing the subtree - [ ] Output validation checks structural components, not exact character matching - [ ] Test coverage >= 97% across all new v3.2.0 functionality ## Subtasks - [ ] **[Epic #8477]** Decision Recording & Persistence — record decisions, persist to DB, implement `plan tree` and `plan explain` - [ ] **[Epic #8480]** Invariant Management System — `invariant add/list/remove`, enforcement during Strategize, persistence - [ ] **[Epic #8481]** Plan Correction Engine — `plan correct --mode=revert|append`, selective subtree recomputation, output validation flexibility ## Child Issues / Child Epics | # | Title | Priority | Status | |---|-------|----------|--------| | #8477 | Epic: Decision Recording & Persistence (v3.2.0) | Critical | 🔲 Open | | #8480 | Epic: Invariant Management System (v3.2.0) | High | 🔲 Open | | #8481 | Epic: Plan Correction Engine (v3.2.0) | High | 🔲 Open | > All three child Epics block this Legendary. This issue should remain open until all Epics are closed and all Acceptance Criteria are verified. ## Definition of Done This Legendary issue should be closed when: 1. All three child Epics (#8477, #8480, #8481) are closed 2. All Acceptance Criteria above are verified and checked off 3. Test coverage >= 97% is confirmed by CI 4. The feature has passed UAT review 5. All related PRs are merged to the main branch --- **Automated by CleverAgents Bot** Supervisor: Epic Planning | Agent: epic-planning-pool-supervisor
HAL9000 added this to the v3.2.0 milestone 2026-04-13 20:06:16 +00:00
Author
Owner

[AUTO-OWNR-2] Triage Decision

Status: Verified

MoSCoW: Must Have
Priority: Critical

Rationale: This Legendary issue is the top-level tracker for the entire Decision Recording & Plan Management system, which is the primary deliverable of the v3.2.0 milestone (M3: Decisions + Validations + Invariants). The milestone acceptance criteria explicitly require decision recording during Strategize and Execute phases, plan tree, plan explain, invariant management, and plan correction — all of which are scoped under this Legendary. It directly maps to the milestone goal and is a non-negotiable requirement for v3.2.0 completion.

Next Steps: Child Epics #8477 (Decision Recording & Persistence), #8480 (Invariant Management System), and #8481 (Plan Correction Engine) must each be triaged, planned, and worked in sequence. This Legendary remains open until all three child Epics are closed, all Acceptance Criteria are checked off, CI confirms ≥ 97% test coverage, and UAT review passes.


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

## [AUTO-OWNR-2] Triage Decision **Status**: ✅ Verified **MoSCoW**: Must Have **Priority**: Critical **Rationale**: This Legendary issue is the top-level tracker for the entire Decision Recording & Plan Management system, which is the primary deliverable of the v3.2.0 milestone (M3: Decisions + Validations + Invariants). The milestone acceptance criteria explicitly require decision recording during Strategize and Execute phases, `plan tree`, `plan explain`, invariant management, and plan correction — all of which are scoped under this Legendary. It directly maps to the milestone goal and is a non-negotiable requirement for v3.2.0 completion. **Next Steps**: Child Epics #8477 (Decision Recording & Persistence), #8480 (Invariant Management System), and #8481 (Plan Correction Engine) must each be triaged, planned, and worked in sequence. This Legendary remains open until all three child Epics are closed, all Acceptance Criteria are checked off, CI confirms ≥ 97% test coverage, and UAT review passes. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor
Author
Owner

[AUTO-EPIC-8] Hierarchy Verification — Cycle 3

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

Child Epics and Their Issues

Epic #8477: Decision Recording & Persistence

  • #8521: feat(decisions): implement Decision data model and database schema
  • #8522: feat(decisions): implement decision recording hook in Strategize phase
  • #8523: feat(decisions): implement decision recording hook in Execute phase
  • #8525: feat(decisions): implement agents plan tree CLI command
  • #8528: feat(decisions): implement agents plan explain CLI command

Epic #8480: Invariant Management System

  • #8524: feat(invariants): implement Invariant data model and database schema
  • #8527: feat(invariants): implement agents invariant add CLI command
  • #8529: feat(invariants): implement agents invariant list CLI command
  • #8530: feat(invariants): implement agents invariant remove CLI command
  • #8532: feat(invariants): implement invariant loading and enforcement in Strategize phase

Epic #8481: Plan Correction Engine

  • #8531: feat(plan-correction): implement correction data model and persistence
  • #8533: feat(plan-correction): implement plan correct --mode=revert with selective subtree recomputation
  • #8534: feat(plan-correction): implement plan correct --mode=append
  • #8535: feat(plan-correction): implement flexible output validation for structural component checks
  • #8537: feat(plan-correction): update agents plan tree to visually reflect corrected nodes

Total child issues: 15 (5 per Epic)

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


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

## [AUTO-EPIC-8] Hierarchy Verification — Cycle 3 The v3.2.0 hierarchy has been verified and is complete. ### Child Epics and Their Issues **Epic #8477: Decision Recording & Persistence** - #8521: feat(decisions): implement Decision data model and database schema - #8522: feat(decisions): implement decision recording hook in Strategize phase - #8523: feat(decisions): implement decision recording hook in Execute phase - #8525: feat(decisions): implement agents plan tree CLI command - #8528: feat(decisions): implement agents plan explain CLI command **Epic #8480: Invariant Management System** - #8524: feat(invariants): implement Invariant data model and database schema - #8527: feat(invariants): implement agents invariant add CLI command - #8529: feat(invariants): implement agents invariant list CLI command - #8530: feat(invariants): implement agents invariant remove CLI command - #8532: feat(invariants): implement invariant loading and enforcement in Strategize phase **Epic #8481: Plan Correction Engine** - #8531: feat(plan-correction): implement correction data model and persistence - #8533: feat(plan-correction): implement plan correct --mode=revert with selective subtree recomputation - #8534: feat(plan-correction): implement plan correct --mode=append - #8535: feat(plan-correction): implement flexible output validation for structural component checks - #8537: feat(plan-correction): update agents plan tree to visually reflect corrected nodes **Total child issues: 15 (5 per Epic)** All child issues are labeled Type/Feature, Priority/High, MoSCoW/Must have, State/Verified and assigned to milestone v3.2.0. --- **Automated by CleverAgents Bot** Supervisor: Epic Planning | Agent: epic-planning-pool-supervisor
Author
Owner

Superseded by next cycle

Superseded by next cycle
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#8475
No description provided.