UAT: `PlanExecutor.run_strategize()` stores decision count in `plan.error_details` — a semantic misuse of the error field #3988

New issue

Open

opened 2026-04-06 08:18:36 +00:00 by freemo · 0 comments

freemo commented

2026-04-06 08:18:36 +00:00

Owner

Metadata

Branch: fix/strategize-decision-storage
Commit Message: fix(plan-executor): store strategize decision metadata in proper field, not error_details
Milestone: None (Backlog)
Parent Epic: #397

Backlog note: This issue was discovered during autonomous operation
on milestone UAT of the Estimation and Planning Intelligence feature area. It does not block milestone completion and has been
placed in the backlog for human review and future milestone assignment.

Bug Report

Feature Area: Estimation and Planning Intelligence — Plan Breakdown into Actions
Severity: Medium — semantic misuse of error_details field causes confusion and potential data loss
Found by: UAT tester (code-level analysis)

Background and Context

The spec defines that the Strategize phase produces a decision tree with a root decision ID and a list of decisions. The Plan domain model has decision_root_id: str | None to store the root decision ULID, and error_details: dict[str, str] | None for error context.

Current Behavior

In PlanExecutor.run_strategize() (src/cleveragents/application/services/plan_executor.py, lines ~490-510), after strategize completes successfully, the decision metadata is stored in plan.error_details:

# Store decisions and invariant records in error_details as
# structured metadata (Plan model uses error_details for
# arbitrary metadata storage until a dedicated field lands)
plan.error_details = {
    "strategy_decisions": str(len(result.decisions)),
    "invariant_records": str(len(result.invariant_records)),
}

This is explicitly acknowledged as a hack in the comment: "until a dedicated field lands."

The problems with this approach:

Semantic confusion: error_details is intended for error context (exception type, traceback). Storing successful strategize metadata there conflates success and failure states.
Data loss on error: If strategize later fails and error_details is overwritten with actual error information, the decision count metadata is lost.
Misleading API: Consumers of plan.error_details (e.g., CLI, API clients) may incorrectly interpret strategize metadata as an error condition.
Type mismatch: error_details: dict[str, str] | None is typed for error strings, not general metadata.

Expected Behavior (per spec)

The Plan domain model should have a dedicated field for strategize phase metadata (decision count, invariant records). The spec describes decisions as first-class entities in the decision tree, and the plan should track this metadata cleanly.

Options:

Add a strategize_metadata: dict[str, Any] | None field to the Plan model
Use the existing decisions: list[dict[str, Any]] field (already on Plan) to store decision log entries
Store decision count in a dedicated decision_count: int field

Code Location

File: src/cleveragents/application/services/plan_executor.py
Method: run_strategize() (lines ~490-510)
Comment: "Plan model uses error_details for arbitrary metadata storage until a dedicated field lands"

Subtasks

Add a dedicated strategize_metadata: dict[str, Any] | None field to the Plan domain model (or use decisions list)
Update PlanExecutor.run_strategize() to store decision metadata in the new field
Ensure error_details is only set on actual errors (not on success)
Update database model and migration if needed
Update unit tests (Behave feature file) to verify correct field usage
Verify CLI agents plan status correctly displays strategize metadata

Definition of Done

plan.error_details is None after a successful strategize phase
Decision count and invariant record count are stored in a semantically correct field
No data loss when strategize succeeds then fails on retry
All existing tests pass
New tests verify the correct field usage
All nox stages pass
Coverage >= 97%
PR merged and issue closed

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-new-issue-creator

## Metadata - **Branch**: `fix/strategize-decision-storage` - **Commit Message**: `fix(plan-executor): store strategize decision metadata in proper field, not error_details` - **Milestone**: None (Backlog) - **Parent Epic**: #397 > **Backlog note:** This issue was discovered during autonomous operation > on milestone UAT of the Estimation and Planning Intelligence feature area. It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. --- ## Bug Report **Feature Area:** Estimation and Planning Intelligence — Plan Breakdown into Actions **Severity:** Medium — semantic misuse of `error_details` field causes confusion and potential data loss **Found by:** UAT tester (code-level analysis) --- ## Background and Context The spec defines that the Strategize phase produces a **decision tree** with a root decision ID and a list of decisions. The `Plan` domain model has `decision_root_id: str | None` to store the root decision ULID, and `error_details: dict[str, str] | None` for error context. ## Current Behavior In `PlanExecutor.run_strategize()` (`src/cleveragents/application/services/plan_executor.py`, lines ~490-510), after strategize completes successfully, the decision metadata is stored in `plan.error_details`: ```python # Store decisions and invariant records in error_details as # structured metadata (Plan model uses error_details for # arbitrary metadata storage until a dedicated field lands) plan.error_details = { "strategy_decisions": str(len(result.decisions)), "invariant_records": str(len(result.invariant_records)), } ``` This is explicitly acknowledged as a hack in the comment: "until a dedicated field lands." The problems with this approach: 1. **Semantic confusion**: `error_details` is intended for error context (exception type, traceback). Storing successful strategize metadata there conflates success and failure states. 2. **Data loss on error**: If strategize later fails and `error_details` is overwritten with actual error information, the decision count metadata is lost. 3. **Misleading API**: Consumers of `plan.error_details` (e.g., CLI, API clients) may incorrectly interpret strategize metadata as an error condition. 4. **Type mismatch**: `error_details: dict[str, str] | None` is typed for error strings, not general metadata. ## Expected Behavior (per spec) The `Plan` domain model should have a dedicated field for strategize phase metadata (decision count, invariant records). The spec describes decisions as first-class entities in the decision tree, and the plan should track this metadata cleanly. Options: 1. Add a `strategize_metadata: dict[str, Any] | None` field to the `Plan` model 2. Use the existing `decisions: list[dict[str, Any]]` field (already on `Plan`) to store decision log entries 3. Store decision count in a dedicated `decision_count: int` field ## Code Location - **File**: `src/cleveragents/application/services/plan_executor.py` - **Method**: `run_strategize()` (lines ~490-510) - **Comment**: "Plan model uses error_details for arbitrary metadata storage until a dedicated field lands" ## Subtasks - [ ] Add a dedicated `strategize_metadata: dict[str, Any] | None` field to the `Plan` domain model (or use `decisions` list) - [ ] Update `PlanExecutor.run_strategize()` to store decision metadata in the new field - [ ] Ensure `error_details` is only set on actual errors (not on success) - [ ] Update database model and migration if needed - [ ] Update unit tests (Behave feature file) to verify correct field usage - [ ] Verify CLI `agents plan status` correctly displays strategize metadata ## Definition of Done - `plan.error_details` is `None` after a successful strategize phase - Decision count and invariant record count are stored in a semantically correct field - No data loss when strategize succeeds then fails on retry - All existing tests pass - New tests verify the correct field usage - All nox stages pass - Coverage >= 97% - PR merged and issue closed --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo added a new dependency

2026-04-06 08:19:11 +00:00

#397 Epic: Server & Autonomy Infrastructure

freemo referenced this issue

2026-04-06 08:19:18 +00:00

[Automated] CleverAgents Build Session - 2026-04-06 #3775

freemo added the

Points

label

2026-04-06 08:20:41 +00:00

freemo referenced this issue

2026-04-06 08:23:38 +00:00