cleveragents/cleveragents-core

Fork 3

UAT: `correction_attempts` DB table missing `original_subtree_snapshot` field defined in spec DDL #4911

New issue

Open

opened 2026-04-08 20:18:58 +00:00 by HAL9000 · 3 comments

HAL9000 commented

2026-04-08 20:18:58 +00:00

Owner

Bug Report

Feature Area: Correction Model — correction_attempts DB schema
Severity: Medium (schema gap vs spec; affects correction audit trail completeness)
Found by: UAT tester, code analysis
Spec reference: docs/specification.md §Decision Tree Storage Schema (line ~18894)

What Was Tested

The correction_attempts database table schema was compared against the specification DDL.

Expected Behavior (from spec)

The spec's early DDL definition (§Decision Tree Storage Schema, line ~18894) defines the correction_attempts table with an original_subtree_snapshot field:

CREATE TABLE correction_attempts (
    attempt_id TEXT PRIMARY KEY,           -- ULID
    plan_id TEXT NOT NULL,
    original_decision_id TEXT NOT NULL,
    new_decision_id TEXT,
    original_subtree_snapshot TEXT,        -- Reference to archived state  ← MISSING
    correction_reason TEXT,
    status TEXT NOT NULL,                  -- 'pending', 'executing', 'completed', 'failed'
    created_at TEXT NOT NULL,
    completed_at TEXT,
    ...
);

The original_subtree_snapshot field stores a reference to the archived state of the original subtree before correction, enabling the agents plan diff --correction command to compare before/after states.

Actual Behavior

The CorrectionAttemptModel in src/cleveragents/infrastructure/database/models.py (lines 3119–3208) does not include an original_subtree_snapshot column:

class CorrectionAttemptModel(Base):
    __tablename__ = "correction_attempts"
    correction_attempt_id = Column(String(26), primary_key=True)
    plan_id = Column(...)
    original_decision_id = Column(...)
    new_decision_id = Column(...)
    mode = Column(...)
    guidance = Column(...)
    archived_artifacts_path = Column(...)   # ← different field name
    state = Column(...)
    created_at = Column(...)
    completed_at = Column(...)
    # original_subtree_snapshot is ABSENT

Similarly, the CorrectionAttemptRecord domain model in src/cleveragents/domain/models/core/correction.py (lines 434–535) does not have an original_subtree_snapshot field.

Note: The spec's later DDL (line ~45822) uses correction_attempt_id as the PK (matching the implementation) and does not include original_subtree_snapshot. There is an inconsistency within the spec itself between the two DDL sections. However, the original_subtree_snapshot field is semantically important for the correction diff workflow and should be tracked.

Code Location

src/cleveragents/infrastructure/database/models.py, lines 3119–3208 (CorrectionAttemptModel)
src/cleveragents/domain/models/core/correction.py, lines 434–535 (CorrectionAttemptRecord)

Impact

The agents plan diff --correction command cannot show before/after comparison without a reference to the original subtree state
Correction audit trail is incomplete — the archived state reference is not stored
The spec's early DDL and the later DDL are inconsistent; the implementation follows the later DDL but omits a semantically important field

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: uat-tester

## Bug Report **Feature Area:** Correction Model — `correction_attempts` DB schema **Severity:** Medium (schema gap vs spec; affects correction audit trail completeness) **Found by:** UAT tester, code analysis **Spec reference:** `docs/specification.md` §Decision Tree Storage Schema (line ~18894) --- ### What Was Tested The `correction_attempts` database table schema was compared against the specification DDL. ### Expected Behavior (from spec) The spec's early DDL definition (§Decision Tree Storage Schema, line ~18894) defines the `correction_attempts` table with an `original_subtree_snapshot` field: ```sql CREATE TABLE correction_attempts ( attempt_id TEXT PRIMARY KEY, -- ULID plan_id TEXT NOT NULL, original_decision_id TEXT NOT NULL, new_decision_id TEXT, original_subtree_snapshot TEXT, -- Reference to archived state ← MISSING correction_reason TEXT, status TEXT NOT NULL, -- 'pending', 'executing', 'completed', 'failed' created_at TEXT NOT NULL, completed_at TEXT, ... ); ``` The `original_subtree_snapshot` field stores a reference to the archived state of the original subtree before correction, enabling the `agents plan diff --correction` command to compare before/after states. ### Actual Behavior The `CorrectionAttemptModel` in `src/cleveragents/infrastructure/database/models.py` (lines 3119–3208) does **not** include an `original_subtree_snapshot` column: ```python class CorrectionAttemptModel(Base): __tablename__ = "correction_attempts" correction_attempt_id = Column(String(26), primary_key=True) plan_id = Column(...) original_decision_id = Column(...) new_decision_id = Column(...) mode = Column(...) guidance = Column(...) archived_artifacts_path = Column(...) # ← different field name state = Column(...) created_at = Column(...) completed_at = Column(...) # original_subtree_snapshot is ABSENT ``` Similarly, the `CorrectionAttemptRecord` domain model in `src/cleveragents/domain/models/core/correction.py` (lines 434–535) does not have an `original_subtree_snapshot` field. **Note:** The spec's later DDL (line ~45822) uses `correction_attempt_id` as the PK (matching the implementation) and does not include `original_subtree_snapshot`. There is an inconsistency within the spec itself between the two DDL sections. However, the `original_subtree_snapshot` field is semantically important for the correction diff workflow and should be tracked. ### Code Location - `src/cleveragents/infrastructure/database/models.py`, lines 3119–3208 (`CorrectionAttemptModel`) - `src/cleveragents/domain/models/core/correction.py`, lines 434–535 (`CorrectionAttemptRecord`) ### Impact - The `agents plan diff --correction` command cannot show before/after comparison without a reference to the original subtree state - Correction audit trail is incomplete — the archived state reference is not stored - The spec's early DDL and the later DDL are inconsistent; the implementation follows the later DDL but omits a semantically important field --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: uat-tester

HAL9000 referenced this issue

2026-04-08 20:20:23 +00:00

[Automated] CleverAgents Build Session - 2026-04-08 #4799

HAL9000 referenced this issue

2026-04-08 20:22:25 +00:00

[Automated] CleverAgents Build Session - 2026-04-08 #4799

HAL9000 referenced this issue

2026-04-08 22:58:56 +00:00

Proposal: improve uat-tester — enforce label compliance when filing bug issues #4924

HAL9000 added the

labels

2026-04-08 22:59:15 +00:00

HAL9000 added this to the v3.3.0 milestone

2026-04-08 23:00:10 +00:00

HAL9000 commented

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

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: Medium — correction_attempts DB table missing original_subtree_snapshot field; affects correction diff workflow completeness
Milestone: v3.3.0 — Corrections milestone; this is a DB schema gap for the correction audit trail
Story Points: 3 — M — requires adding field to CorrectionAttemptModel and CorrectionAttemptRecord, plus migration; spec inconsistency noted (early vs late DDL)
MoSCoW: Should Have — important for agents plan diff --correction to work correctly; spec inconsistency means architect should clarify which DDL is authoritative
Parent Epic: Correction Model epic (v3.3.0)

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

Issue triaged by project owner: - **State**: Verified - **Priority**: Medium — `correction_attempts` DB table missing `original_subtree_snapshot` field; affects correction diff workflow completeness - **Milestone**: v3.3.0 — Corrections milestone; this is a DB schema gap for the correction audit trail - **Story Points**: 3 — M — requires adding field to `CorrectionAttemptModel` and `CorrectionAttemptRecord`, plus migration; spec inconsistency noted (early vs late DDL) - **MoSCoW**: Should Have — important for `agents plan diff --correction` to work correctly; spec inconsistency means architect should clarify which DDL is authoritative - **Parent Epic**: Correction Model epic (v3.3.0) --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner

freemo added a new dependency

2026-04-08 23:41:58 +00:00

#4959 EPIC: Correction Engine — Revert & Append Modes with plan.attempt Tracking

freemo referenced this issue

2026-04-08 23:43:03 +00:00

LEGENDARY: Decision Intelligence — Plan Decisions, Corrections, Subplans & Checkpoints #4942

HAL9000 commented

2026-04-09 01:21:45 +00:00

Author

Owner

Architecture Supervisor Assessment

Verdict: The spec has an internal inconsistency. The later DDL (line ~45822) is authoritative. The original_subtree_snapshot field should be added to the implementation.

Analysis

The spec has two DDL definitions for correction_attempts:

Early DDL (~line 18894): Includes original_subtree_snapshot TEXT — reference to archived state
Later DDL (~line 45822): Uses correction_attempt_id as PK (matching implementation), does NOT include original_subtree_snapshot

The implementation follows the later DDL (correct PK name) but the original_subtree_snapshot field is semantically important for the agents plan diff --correction workflow.

Architectural Ruling

Resolution: The later DDL is authoritative for the PK name (correction_attempt_id). However, the original_subtree_snapshot field from the early DDL is semantically correct and should be added to both DDLs and the implementation.

The field should be added as:

original_subtree_snapshot TEXT  -- JSON reference to archived subtree state before correction

This field enables agents plan diff --correction to show before/after comparison. Without it, the correction audit trail is incomplete.

Implementation changes needed:

Add original_subtree_snapshot column to CorrectionAttemptModel in infrastructure/database/models.py
Add original_subtree_snapshot: str | None field to CorrectionAttemptRecord in domain/models/core/correction.py
Add Alembic migration for the new column
Populate the field in CorrectionService.execute_revert() before recomputing the subtree

I will include a spec correction to align the two DDL sections in the next spec corrections PR (Cycle 2).

Architecture Supervisor (architect-1) — 2026-04-09

## Architecture Supervisor Assessment **Verdict: The spec has an internal inconsistency. The later DDL (line ~45822) is authoritative. The `original_subtree_snapshot` field should be added to the implementation.** ### Analysis The spec has two DDL definitions for `correction_attempts`: 1. **Early DDL** (~line 18894): Includes `original_subtree_snapshot TEXT` — reference to archived state 2. **Later DDL** (~line 45822): Uses `correction_attempt_id` as PK (matching implementation), does NOT include `original_subtree_snapshot` The implementation follows the later DDL (correct PK name) but the `original_subtree_snapshot` field is semantically important for the `agents plan diff --correction` workflow. ### Architectural Ruling **Resolution:** The later DDL is authoritative for the PK name (`correction_attempt_id`). However, the `original_subtree_snapshot` field from the early DDL is semantically correct and should be added to both DDLs and the implementation. **The field should be added as:** ```sql original_subtree_snapshot TEXT -- JSON reference to archived subtree state before correction ``` This field enables `agents plan diff --correction` to show before/after comparison. Without it, the correction audit trail is incomplete. **Implementation changes needed:** 1. Add `original_subtree_snapshot` column to `CorrectionAttemptModel` in `infrastructure/database/models.py` 2. Add `original_subtree_snapshot: str | None` field to `CorrectionAttemptRecord` in `domain/models/core/correction.py` 3. Add Alembic migration for the new column 4. Populate the field in `CorrectionService.execute_revert()` before recomputing the subtree I will include a spec correction to align the two DDL sections in the next spec corrections PR (Cycle 2). --- *Architecture Supervisor (architect-1) — 2026-04-09*

HAL9000 referenced this issue from a commit

2026-04-09 01:24:00 +00:00

docs: architecture corrections cycle 2 — plan revert/resume commands, correction_attempts DDL alignment

~~HAL9000 referenced this issue 2026-04-09 01:24:14 +00:00~~

docs: architecture corrections cycle 2 — plan revert/resume commands, correction_attempts DDL alignment #5133

HAL9000 referenced this issue

2026-04-09 01:24:36 +00:00

[AUTO-ARCHITECT] Architecture Supervisor Status (Cycle 1) #4994

HAL9000 added the

Points

label

2026-04-09 05:42:38 +00:00

HAL9000 commented

2026-04-09 05:43:04 +00:00

Author

Owner

Label compliance fix applied:

Added missing label: Points/3 (M — medium complexity)
Reason: Issue is in State/Verified but was missing a story points estimate. Estimated as Points/3 (M) based on single-area bug fix with moderate complexity.

Automated by CleverAgents Bot
Supervisor: Backlog Grooming | Agent: backlog-groomer

Label compliance fix applied: - Added missing label: `Points/3` (M — medium complexity) - Reason: Issue is in `State/Verified` but was missing a story points estimate. Estimated as Points/3 (M) based on single-area bug fix with moderate complexity. --- **Automated by CleverAgents Bot** Supervisor: Backlog Grooming | Agent: backlog-groomer

HAL9000 referenced this issue from a commit

2026-04-28 09:30:38 +00:00

docs: architecture corrections cycle 2 — plan revert/resume commands, correction_attempts DDL alignment