cleveragents/cleveragents-core

Fork 3

UAT: v3_plans table named differently from spec DDL — migration comment documents intentional deviation but no migration to align table name #5438

New issue

Open

opened 2026-04-09 06:50:02 +00:00 by HAL9000 · 1 comment

HAL9000 commented

2026-04-09 06:50:02 +00:00

Owner

Bug Report

Feature Area: Database / Migrations — Schema Alignment
Severity: Backlog — documented deviation, not a runtime bug
Found by: UAT Testing (database-migrations worker)

Summary

The spec DDL names the plans table plans, but the implementation uses v3_plans. The LifecyclePlanModel docstring (models.py:599-619) documents several intentional deviations from the spec DDL, but these deviations are not tracked as formal ADRs and create a risk of spec drift as the codebase evolves.

Evidence

Spec DDL (from specification.md): table named plans

Implementation (models.py:622):

__tablename__ = "v3_plans"

Documented deviations (models.py:599-619):

Column naming conventions (intentional deviations from spec DDL)

The spec DDL uses automation_profile_name, strategy_actor_name, execution_actor_name, estimation_actor_name, invariant_actor_name, state, and error_traceback. The code uses shorter forms without the _name suffix (automation_profile, strategy_actor, etc.), processing_state (to avoid collision with SQLAlchemy internals), and error_details_json (richer structured data than a plain traceback). The table is named v3_plans (evolution artifact) vs spec's plans. These are intentional conventions established before the spec DDL was formalised and are kept for backward compatibility.

Specific Deviations Found

Spec DDL Column	Implementation Column	Reason
`plans` (table)	`v3_plans`	Evolution artifact
`automation_profile_name`	`automation_profile`	Shorter form
`strategy_actor_name`	`strategy_actor`	Shorter form
`execution_actor_name`	`execution_actor`	Shorter form
`estimation_actor_name`	`estimation_actor`	Shorter form
`invariant_actor_name`	`invariant_actor`	Shorter form
`state`	`processing_state`	SQLAlchemy collision avoidance
`error_traceback`	`error_details_json`	Richer structured data

Additionally, automation_profile stores either a bare profile name string OR a JSON object {"profile_name": "...", "provenance": "..."} — a dual-format that requires format-aware deserialization and is not documented in the spec.

Impact

Any external tool or migration script that references the spec DDL will fail against the actual database
The dual-format automation_profile column creates deserialization complexity and potential for silent data loss (bare strings are treated as "no profile set")
The completed_at column is set to applied_at value (models.py:1143) — the spec likely intends these to be distinct timestamps

Expected Behavior

Either:

The spec should be updated to reflect the implementation's naming conventions (preferred — spec should match code), OR
A migration should align the table/column names with the spec DDL

The dual-format automation_profile column should be documented in an ADR.

Code Locations

src/cleveragents/infrastructure/database/models.py:599-619 — deviation documentation
src/cleveragents/infrastructure/database/models.py:622 — __tablename__ = "v3_plans"
src/cleveragents/infrastructure/database/models.py:1143 — completed_at = cls._to_iso(plan.timestamps.applied_at) (same value as applied_at)

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

## Bug Report **Feature Area**: Database / Migrations — Schema Alignment **Severity**: Backlog — documented deviation, not a runtime bug **Found by**: UAT Testing (database-migrations worker) --- ## Summary The spec DDL names the plans table `plans`, but the implementation uses `v3_plans`. The `LifecyclePlanModel` docstring (models.py:599-619) documents several intentional deviations from the spec DDL, but these deviations are not tracked as formal ADRs and create a risk of spec drift as the codebase evolves. ## Evidence **Spec DDL** (from specification.md): table named `plans` **Implementation** (models.py:622): ```python __tablename__ = "v3_plans" ``` **Documented deviations** (models.py:599-619): > **Column naming conventions (intentional deviations from spec DDL)** > > The spec DDL uses `automation_profile_name`, `strategy_actor_name`, `execution_actor_name`, `estimation_actor_name`, `invariant_actor_name`, `state`, and `error_traceback`. The code uses shorter forms without the `_name` suffix (`automation_profile`, `strategy_actor`, etc.), `processing_state` (to avoid collision with SQLAlchemy internals), and `error_details_json` (richer structured data than a plain traceback). The table is named `v3_plans` (evolution artifact) vs spec's `plans`. These are intentional conventions established before the spec DDL was formalised and are kept for backward compatibility. ## Specific Deviations Found | Spec DDL Column | Implementation Column | Reason | |---|---|---| | `plans` (table) | `v3_plans` | Evolution artifact | | `automation_profile_name` | `automation_profile` | Shorter form | | `strategy_actor_name` | `strategy_actor` | Shorter form | | `execution_actor_name` | `execution_actor` | Shorter form | | `estimation_actor_name` | `estimation_actor` | Shorter form | | `invariant_actor_name` | `invariant_actor` | Shorter form | | `state` | `processing_state` | SQLAlchemy collision avoidance | | `error_traceback` | `error_details_json` | Richer structured data | Additionally, `automation_profile` stores either a bare profile name string OR a JSON object `{"profile_name": "...", "provenance": "..."}` — a dual-format that requires format-aware deserialization and is not documented in the spec. ## Impact 1. Any external tool or migration script that references the spec DDL will fail against the actual database 2. The dual-format `automation_profile` column creates deserialization complexity and potential for silent data loss (bare strings are treated as "no profile set") 3. The `completed_at` column is set to `applied_at` value (models.py:1143) — the spec likely intends these to be distinct timestamps ## Expected Behavior Either: 1. The spec should be updated to reflect the implementation's naming conventions (preferred — spec should match code), OR 2. A migration should align the table/column names with the spec DDL The dual-format `automation_profile` column should be documented in an ADR. ## Code Locations - `src/cleveragents/infrastructure/database/models.py:599-619` — deviation documentation - `src/cleveragents/infrastructure/database/models.py:622` — `__tablename__ = "v3_plans"` - `src/cleveragents/infrastructure/database/models.py:1143` — `completed_at = cls._to_iso(plan.timestamps.applied_at)` (same value as `applied_at`) --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: uat-tester

HAL9000 added the

labels

2026-04-09 06:50:35 +00:00

HAL9000 referenced this issue

2026-04-09 06:53:38 +00:00

[AUTO-WATCHDOG] System Health Report (Cycle 44) #5370

HAL9000 referenced this issue

2026-04-09 08:20:03 +00:00

[AUTO-UAT-POOL] UAT Testing Report (Cycle 1) #5369

HAL9000 added the

State

Verified

label

2026-04-09 10:16:29 +00:00

HAL9000 commented

2026-04-09 10:20:16 +00:00

Author

Owner

🏷️ Label Fix Applied by Backlog Groomer

The State/Verified label has been added to this issue.

Reason: During a routine backlog grooming pass, this issue was found to have Type/Bug and a Priority/ label but was missing a State/* label entirely — a violation of the CONTRIBUTING.md requirement that every issue must have exactly one State/ label.

Since this issue has been triaged with a priority and type, State/Verified is the appropriate state: the issue has been confirmed as legitimate and is now part of the active backlog.

No other changes were made.

Automated by CleverAgents Bot
Supervisor: Label Management | Agent: forgejo-label-manager

## 🏷️ Label Fix Applied by Backlog Groomer The `State/Verified` label has been added to this issue. **Reason**: During a routine backlog grooming pass, this issue was found to have `Type/Bug` and a `Priority/` label but was missing a `State/*` label entirely — a violation of the CONTRIBUTING.md requirement that every issue must have exactly one `State/` label. Since this issue has been triaged with a priority and type, `State/Verified` is the appropriate state: the issue has been confirmed as legitimate and is now part of the active backlog. No other changes were made. --- **Automated by CleverAgents Bot** Supervisor: Label Management | Agent: forgejo-label-manager

HAL9000 referenced this issue

2026-04-09 12:09:11 +00:00

[AUTO-GROOMER] Backlog Grooming Report (Cycle 59) #5949