cleveragents/cleveragents-core

Fork 3

UAT: `LifecyclePlanModel` uses table name `v3_plans` instead of spec-required `plans` — permanent schema divergence from specification DDL #3966

New issue

Open

opened 2026-04-06 07:58:14 +00:00 by freemo · 1 comment

freemo commented

2026-04-06 07:58:14 +00:00

Owner

Metadata

Branch: fix/db-rename-v3-plans-to-plans
Commit Message: fix(db): rename v3_plans table to spec-aligned plans table name
Milestone: (none — routed to backlog per Milestone Scope Guard)
Parent Epic: (orphan — needs manual linking; see comment below)

Bug Report

Feature Area: Infrastructure and Database Layer
Severity: Medium — permanent schema divergence from specification; external tools and documentation referencing the spec DDL will not work
Found by: UAT tester (code analysis)

What Was Tested

Code analysis of src/cleveragents/infrastructure/database/models.py LifecyclePlanModel against the specification's "Core tables (SQLite DDL)" section.

Expected Behavior (from spec)

The specification's "Database Schema Design" section defines the plans table as:

CREATE TABLE plans (
    plan_id TEXT PRIMARY KEY,  -- ULID
    parent_plan_id TEXT REFERENCES plans(plan_id),
    root_plan_id TEXT NOT NULL REFERENCES plans(plan_id),
    action_name TEXT NOT NULL,
    phase TEXT NOT NULL DEFAULT 'strategize',
    state TEXT NOT NULL DEFAULT 'queued',
    ...
);

The table name is plans.

Actual Behavior

LifecyclePlanModel uses v3_plans as the table name:

# models.py line 604
__tablename__ = "v3_plans"

The code comment (lines 581-601) acknowledges this divergence:

"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."

Additionally, the spec defines state as the column name, but the code uses processing_state (to avoid collision with SQLAlchemy internals). The spec defines automation_profile_name but the code uses automation_profile.

Impact

External tooling: Any tool, script, or documentation that queries the database using the spec DDL table name plans will fail — the table doesn't exist.
Migration complexity: Future migrations that reference the spec DDL will need to account for the v3_plans naming.
Developer confusion: New developers reading the spec and then the code will be confused by the mismatch.
A2A protocol: The spec's A2A extension methods reference plan operations — if any external A2A client inspects the database schema, it will find v3_plans instead of plans.
agents init reset: The spec states agents init "re-creates the global config and database" — if the spec DDL is used for reset, it will create a plans table that conflicts with v3_plans.

Code Location

src/cleveragents/infrastructure/database/models.py (line 604, __tablename__ = "v3_plans")
src/cleveragents/infrastructure/database/models.py (lines 581-601, comment documenting the divergence)

Fix Required

Two options:

Option A (Preferred): Create a migration to rename v3_plans to plans and update all FK references. This aligns the schema with the spec and eliminates the divergence.

Option B: Update the specification to formally document v3_plans as the canonical table name, and update all spec DDL references accordingly.

The code comment says this is "kept for backward compatibility" but since this is a local SQLite database (not a shared production database), a migration rename is feasible and would eliminate the long-term maintenance burden of tracking this divergence.

Subtasks

Write failing Behave scenario reproducing the v3_plans vs plans table name mismatch (TDD — failing test first)
Decide on Option A (migration rename) or Option B (update spec) — requires human review
(If Option A) Create Alembic migration to rename v3_plans → plans
(If Option A) Update all FK references and ORM queries from v3_plans to plans
(If Option A) Update LifecyclePlanModel.__tablename__ to "plans"
(If Option A) Evaluate processing_state → state and automation_profile → automation_profile_name column renames for full spec alignment
(If Option B) Update docs/specification.md DDL to formally document v3_plans as canonical
Run full nox suite to confirm no regressions
Create PR and obtain two approving reviews

Definition of Done

The chosen option (A or B) is fully implemented with no partial divergence remaining
A failing test was committed before the fix (TDD compliance)
All existing tests pass with the change applied
No unresolved references to the old table name remain in production code
All nox stages pass
Coverage >= 97%

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

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

## Metadata - **Branch**: `fix/db-rename-v3-plans-to-plans` - **Commit Message**: `fix(db): rename v3_plans table to spec-aligned plans table name` - **Milestone**: _(none — routed to backlog per Milestone Scope Guard)_ - **Parent Epic**: _(orphan — needs manual linking; see comment below)_ --- ## Bug Report **Feature Area:** Infrastructure and Database Layer **Severity:** Medium — permanent schema divergence from specification; external tools and documentation referencing the spec DDL will not work **Found by:** UAT tester (code analysis) --- ## What Was Tested Code analysis of `src/cleveragents/infrastructure/database/models.py` `LifecyclePlanModel` against the specification's "Core tables (SQLite DDL)" section. ## Expected Behavior (from spec) The specification's "Database Schema Design" section defines the plans table as: ```sql CREATE TABLE plans ( plan_id TEXT PRIMARY KEY, -- ULID parent_plan_id TEXT REFERENCES plans(plan_id), root_plan_id TEXT NOT NULL REFERENCES plans(plan_id), action_name TEXT NOT NULL, phase TEXT NOT NULL DEFAULT 'strategize', state TEXT NOT NULL DEFAULT 'queued', ... ); ``` The table name is `plans`. ## Actual Behavior `LifecyclePlanModel` uses `v3_plans` as the table name: ```python # models.py line 604 __tablename__ = "v3_plans" ``` The code comment (lines 581-601) acknowledges this divergence: > "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." Additionally, the spec defines `state` as the column name, but the code uses `processing_state` (to avoid collision with SQLAlchemy internals). The spec defines `automation_profile_name` but the code uses `automation_profile`. ## Impact 1. **External tooling:** Any tool, script, or documentation that queries the database using the spec DDL table name `plans` will fail — the table doesn't exist. 2. **Migration complexity:** Future migrations that reference the spec DDL will need to account for the `v3_plans` naming. 3. **Developer confusion:** New developers reading the spec and then the code will be confused by the mismatch. 4. **A2A protocol:** The spec's A2A extension methods reference plan operations — if any external A2A client inspects the database schema, it will find `v3_plans` instead of `plans`. 5. **`agents init` reset:** The spec states `agents init` "re-creates the global config and database" — if the spec DDL is used for reset, it will create a `plans` table that conflicts with `v3_plans`. ## Code Location - `src/cleveragents/infrastructure/database/models.py` (line 604, `__tablename__ = "v3_plans"`) - `src/cleveragents/infrastructure/database/models.py` (lines 581-601, comment documenting the divergence) ## Fix Required Two options: **Option A (Preferred):** Create a migration to rename `v3_plans` to `plans` and update all FK references. This aligns the schema with the spec and eliminates the divergence. **Option B:** Update the specification to formally document `v3_plans` as the canonical table name, and update all spec DDL references accordingly. The code comment says this is "kept for backward compatibility" but since this is a local SQLite database (not a shared production database), a migration rename is feasible and would eliminate the long-term maintenance burden of tracking this divergence. --- ## Subtasks - [ ] Write failing Behave scenario reproducing the `v3_plans` vs `plans` table name mismatch (TDD — failing test first) - [ ] Decide on Option A (migration rename) or Option B (update spec) — requires human review - [ ] _(If Option A)_ Create Alembic migration to rename `v3_plans` → `plans` - [ ] _(If Option A)_ Update all FK references and ORM queries from `v3_plans` to `plans` - [ ] _(If Option A)_ Update `LifecyclePlanModel.__tablename__` to `"plans"` - [ ] _(If Option A)_ Evaluate `processing_state` → `state` and `automation_profile` → `automation_profile_name` column renames for full spec alignment - [ ] _(If Option B)_ Update `docs/specification.md` DDL to formally document `v3_plans` as canonical - [ ] Run full `nox` suite to confirm no regressions - [ ] Create PR and obtain two approving reviews ## Definition of Done - [ ] The chosen option (A or B) is fully implemented with no partial divergence remaining - [ ] A failing test was committed before the fix (TDD compliance) - [ ] All existing tests pass with the change applied - [ ] No unresolved references to the old table name remain in production code - [ ] All nox stages pass - [ ] Coverage >= 97% --- > **Backlog note:** This issue was discovered during autonomous operation > on milestone UAT. It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo commented

2026-04-06 07:58:32 +00:00

Author

Owner

⚠️ Orphan Issue — Needs Manual Linking

This issue was created without a known parent Epic. Per CONTRIBUTING.md, orphan issues are not permitted — every Issue must be linked to a parent Epic.

Action required: A project maintainer must:

Identify the appropriate parent Epic for this database schema divergence bug (likely the Epic covering the Infrastructure/Database Layer or Plan Lifecycle workstream).
Create the dependency link so that this issue blocks the parent Epic (child blocks parent direction).

This can be done via the Forgejo UI under the issue's "Dependencies" section, or via the API:

curl -X POST "https://git.cleverthis.com/api/v1/repos/cleveragents/cleveragents-core/issues/3966/blocks" \
  -H "Authorization: token <PAT>" \
  -H "Content-Type: application/json" \
  -d '{"owner": "cleveragents", "repo": "cleveragents-core", "index": <PARENT_EPIC_NUMBER>}'

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

⚠️ **Orphan Issue — Needs Manual Linking** This issue was created without a known parent Epic. Per CONTRIBUTING.md, orphan issues are not permitted — every Issue must be linked to a parent Epic. **Action required:** A project maintainer must: 1. Identify the appropriate parent Epic for this database schema divergence bug (likely the Epic covering the Infrastructure/Database Layer or Plan Lifecycle workstream). 2. Create the dependency link so that this issue **blocks** the parent Epic (child blocks parent direction). This can be done via the Forgejo UI under the issue's "Dependencies" section, or via the API: ```bash curl -X POST "https://git.cleverthis.com/api/v1/repos/cleveragents/cleveragents-core/issues/3966/blocks" \ -H "Authorization: token <PAT>" \ -H "Content-Type: application/json" \ -d '{"owner": "cleveragents", "repo": "cleveragents-core", "index": <PARENT_EPIC_NUMBER>}' ``` --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo added the

Points

label

2026-04-06 07:58:55 +00:00

freemo referenced this issue

2026-04-06 07:59:14 +00:00

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

freemo referenced this issue

2026-04-06 08:09:29 +00:00

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

freemo referenced this issue

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