Epic: Decision Recording & Persistence (v3.2.0) #8477

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

Metadata

  • Commit message: feat(decisions): implement decision recording, context snapshots, DB persistence, plan tree and plan explain CLI
  • Branch name: feat/v3.2.0-decision-recording-persistence

Background and Context

As part of the v3.2.0 milestone (M3: Decisions + Validations + Invariants), the agent system needs to record every decision made during the Strategize and Execute phases. Currently, no persistent audit trail exists — once a plan runs, there is no way to review what decisions were made, what alternatives were considered, or why a particular path was chosen.

This Epic delivers the core decision recording infrastructure: capturing decisions with full context snapshots, persisting them to the database, and exposing them via two new CLI commands (agents plan tree and agents plan explain).

This Epic blocks the parent Legendary issue #8475.

Expected Behavior

  • During Strategize and Execute phases, every decision is captured with a full context snapshot (inputs, outputs, alternatives considered, rationale)
  • Decision records are written to the database atomically with the plan execution
  • agents plan tree renders a visual tree of all decisions in a plan, showing the hierarchy and status of each node
  • agents plan explain <decision-id> displays full details for a single decision: context, rationale, alternatives considered, and outcome

Acceptance Criteria

  • Decisions are recorded during Strategize phase with full context snapshots
  • Decisions are recorded during Execute phase with full context snapshots
  • Decision records include: decision ID, phase, timestamp, context snapshot, alternatives considered, rationale, and outcome
  • Decision data is persisted to the database (durable across restarts)
  • agents plan tree renders the decision tree correctly, showing hierarchy
  • agents plan explain <id> shows full decision details including alternatives considered
  • Database schema migrations are included and reversible
  • Test coverage >= 97% for all new code in this Epic

Subtasks

  • Design and implement the Decision data model and database schema
  • Write and apply database migration for the decisions table
  • Implement decision recording hook in the Strategize phase
  • Implement decision recording hook in the Execute phase
  • Implement context snapshot capture (inputs, outputs, alternatives, rationale)
  • Implement agents plan tree CLI command with tree rendering
  • Implement agents plan explain CLI command with full detail output
  • Write unit tests for decision recording logic (>= 97% coverage)
  • Write integration tests for plan tree and plan explain CLI commands
  • Update documentation / help text for new CLI commands

Child Issues / Child Epics

Child implementation issues linked below.

# Title Status
#8521 Implement Decision data model & DB schema 🔲 Open
#8522 Implement decision recording in Strategize phase 🔲 Open
#8523 Implement decision recording in Execute phase 🔲 Open
#8525 Implement agents plan tree CLI command 🔲 Open
#8528 Implement agents plan explain CLI command 🔲 Open

Definition of Done

This Epic should be closed when:

  1. All Acceptance Criteria above are verified and checked off
  2. All child implementation issues are closed
  3. Test coverage >= 97% is confirmed by CI for all new code
  4. Code has passed peer review and been merged to the main branch
  5. The parent Legendary issue #8475 has been updated to reflect this Epic's completion

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

## Metadata - **Commit message**: `feat(decisions): implement decision recording, context snapshots, DB persistence, plan tree and plan explain CLI` - **Branch name**: `feat/v3.2.0-decision-recording-persistence` ## Background and Context As part of the v3.2.0 milestone (M3: Decisions + Validations + Invariants), the agent system needs to record every decision made during the Strategize and Execute phases. Currently, no persistent audit trail exists — once a plan runs, there is no way to review what decisions were made, what alternatives were considered, or why a particular path was chosen. This Epic delivers the core decision recording infrastructure: capturing decisions with full context snapshots, persisting them to the database, and exposing them via two new CLI commands (`agents plan tree` and `agents plan explain`). This Epic blocks the parent Legendary issue #8475. ## Expected Behavior - During Strategize and Execute phases, every decision is captured with a full context snapshot (inputs, outputs, alternatives considered, rationale) - Decision records are written to the database atomically with the plan execution - `agents plan tree` renders a visual tree of all decisions in a plan, showing the hierarchy and status of each node - `agents plan explain <decision-id>` displays full details for a single decision: context, rationale, alternatives considered, and outcome ## Acceptance Criteria - [ ] Decisions are recorded during Strategize phase with full context snapshots - [ ] Decisions are recorded during Execute phase with full context snapshots - [ ] Decision records include: decision ID, phase, timestamp, context snapshot, alternatives considered, rationale, and outcome - [ ] Decision data is persisted to the database (durable across restarts) - [ ] `agents plan tree` renders the decision tree correctly, showing hierarchy - [ ] `agents plan explain <id>` shows full decision details including alternatives considered - [ ] Database schema migrations are included and reversible - [ ] Test coverage >= 97% for all new code in this Epic ## Subtasks - [ ] Design and implement the `Decision` data model and database schema - [ ] Write and apply database migration for the decisions table - [ ] Implement decision recording hook in the Strategize phase - [ ] Implement decision recording hook in the Execute phase - [ ] Implement context snapshot capture (inputs, outputs, alternatives, rationale) - [ ] Implement `agents plan tree` CLI command with tree rendering - [ ] Implement `agents plan explain` CLI command with full detail output - [ ] Write unit tests for decision recording logic (>= 97% coverage) - [ ] Write integration tests for `plan tree` and `plan explain` CLI commands - [ ] Update documentation / help text for new CLI commands ## Child Issues / Child Epics > Child implementation issues linked below. | # | Title | Status | |---|-------|--------| | #8521 | Implement Decision data model & DB schema | 🔲 Open | | #8522 | Implement decision recording in Strategize phase | 🔲 Open | | #8523 | Implement decision recording in Execute phase | 🔲 Open | | #8525 | Implement `agents plan tree` CLI command | 🔲 Open | | #8528 | Implement `agents plan explain` CLI command | 🔲 Open | ## Definition of Done This Epic should be closed when: 1. All Acceptance Criteria above are verified and checked off 2. All child implementation issues are closed 3. Test coverage >= 97% is confirmed by CI for all new code 4. Code has passed peer review and been merged to the main branch 5. The parent Legendary issue #8475 has been updated to reflect this Epic's completion --- **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 Epic is the foundational building block of the v3.2.0 milestone. Without decision recording and persistence, none of the higher-level features (invariant enforcement, plan correction) can function — they all depend on a durable decision audit trail in the database. The milestone acceptance criteria explicitly call out decision recording during Strategize and Execute phases, plan tree, and plan explain as required deliverables. This Epic directly blocks the parent Legendary #8475 and is a hard prerequisite for v3.2.0 completion.

Next Steps: Child implementation issues should be created for: (1) Decision data model & DB schema, (2) decision recording hook in Strategize phase, (3) decision recording hook in Execute phase, (4) agents plan tree CLI command, (5) agents plan explain CLI command. Each child issue should target ≥ 97% test coverage. This Epic should be picked up as the first v3.2.0 implementation work item.


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 Epic is the foundational building block of the v3.2.0 milestone. Without decision recording and persistence, none of the higher-level features (invariant enforcement, plan correction) can function — they all depend on a durable decision audit trail in the database. The milestone acceptance criteria explicitly call out decision recording during Strategize and Execute phases, `plan tree`, and `plan explain` as required deliverables. This Epic directly blocks the parent Legendary #8475 and is a hard prerequisite for v3.2.0 completion. **Next Steps**: Child implementation issues should be created for: (1) Decision data model & DB schema, (2) decision recording hook in Strategize phase, (3) decision recording hook in Execute phase, (4) `agents plan tree` CLI command, (5) `agents plan explain` CLI command. Each child issue should target ≥ 97% test coverage. This Epic should be picked up as the first v3.2.0 implementation work item. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor
Author
Owner

Child Implementation Issues Created

All 5 child implementation issues for this Epic have been created and linked. Each issue is assigned to milestone v3.2.0 (ID: 105) and labelled with Type/Feature, Priority/High, MoSCoW/Must have, and State/Verified.

# Title Branch Prefix Labels
#8521 feat(decisions): implement Decision data model and database schema feat/v3.2.0-decision-data-model-db-schema Type/Feature, Priority/High, MoSCoW/Must have, State/Verified
#8522 feat(decisions): implement decision recording hook in Strategize phase feat/v3.2.0-decision-recording-strategize Type/Feature, Priority/High, MoSCoW/Must have, State/Verified
#8523 feat(decisions): implement decision recording hook in Execute phase feat/v3.2.0-decision-recording-execute Type/Feature, Priority/High, MoSCoW/Must have, State/Verified
#8525 feat(decisions): implement agents plan tree CLI command feat/v3.2.0-plan-tree-cli Type/Feature, Priority/High, MoSCoW/Must have, State/Verified
#8528 feat(decisions): implement agents plan explain CLI command feat/v3.2.0-plan-explain-cli Type/Feature, Priority/High, MoSCoW/Must have, State/Verified

Each child issue blocks this Epic (#8477). The Epic body has been updated to replace all TBD entries with the actual issue numbers above.


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

## ✅ Child Implementation Issues Created All 5 child implementation issues for this Epic have been created and linked. Each issue is assigned to milestone **v3.2.0** (ID: 105) and labelled with `Type/Feature`, `Priority/High`, `MoSCoW/Must have`, and `State/Verified`. | # | Title | Branch Prefix | Labels | |---|-------|---------------|--------| | #8521 | feat(decisions): implement Decision data model and database schema | `feat/v3.2.0-decision-data-model-db-schema` | Type/Feature, Priority/High, MoSCoW/Must have, State/Verified | | #8522 | feat(decisions): implement decision recording hook in Strategize phase | `feat/v3.2.0-decision-recording-strategize` | Type/Feature, Priority/High, MoSCoW/Must have, State/Verified | | #8523 | feat(decisions): implement decision recording hook in Execute phase | `feat/v3.2.0-decision-recording-execute` | Type/Feature, Priority/High, MoSCoW/Must have, State/Verified | | #8525 | feat(decisions): implement agents plan tree CLI command | `feat/v3.2.0-plan-tree-cli` | Type/Feature, Priority/High, MoSCoW/Must have, State/Verified | | #8528 | feat(decisions): implement agents plan explain CLI command | `feat/v3.2.0-plan-explain-cli` | Type/Feature, Priority/High, MoSCoW/Must have, State/Verified | Each child issue blocks this Epic (#8477). The Epic body has been updated to replace all TBD entries with the actual issue numbers above. --- **Automated by CleverAgents Bot** Supervisor: Epic Planning | Agent: epic-planning-pool-supervisor
Owner

Implementation Attempt — Tier 1: qwen-large — Success

Implemented ExecutePhaseDecisionHook for Epic #8477 (v3.2.0 - Decision Recording & Persistence).

The hook is the Execute-phase mirror of StrategizeDecisionHook, providing six recording methods:

  • implementation_choice, tool_invocation, error_recovery, validation_response
  • subplan_spawn, subplan_parallel_spawn, resource_selection (Execute-phase)

Each decision captures full context snapshots and persists atomically via DecisionService.

PR: #11154
Branch: feat/v3.2.0-decision-recording-persistence


Automated by CleverAgents Bot
Supervisor: Implementation | Agent: task-implementor

**Implementation Attempt** — Tier 1: qwen-large — Success Implemented ``ExecutePhaseDecisionHook`` for Epic #8477 (v3.2.0 - Decision Recording & Persistence). The hook is the Execute-phase mirror of ``StrategizeDecisionHook``, providing six recording methods: - implementation_choice, tool_invocation, error_recovery, validation_response - subplan_spawn, subplan_parallel_spawn, resource_selection (Execute-phase) Each decision captures full context snapshots and persists atomically via DecisionService. **PR:** https://git.cleverthis.com/cleveragents/cleveragents-core/pulls/11154 **Branch:** feat/v3.2.0-decision-recording-persistence --- Automated by CleverAgents Bot Supervisor: Implementation | Agent: task-implementor
Sign in to join this conversation.
No milestone
No project
No assignees
2 participants
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#8477
No description provided.