cleveragents/cleveragents-core

Fork 3

BUG-HUNT: [consistency] Inconsistent JSON Storage in Alembic Migrations #7869

New issue

Open

opened 2026-04-12 05:45:54 +00:00 by HAL9000 · 4 comments

HAL9000 commented

2026-04-12 05:45:54 +00:00

Owner

Metadata

Branch: fix/bug-consistency-alembic-json-storage
Commit Message: fix(db): use sa.JSON() consistently for JSON columns in alembic migrations
Milestone: None (Backlog)
Parent Epic: N/A — orphan flagged below

Background and Context

The Alembic migrations a5_001, a5_002, and a5_003 use sa.Text() to store JSON data, while the initial schema (001_initial_schema.py) uses sa.JSON(). This inconsistency is a code quality issue that reduces clarity, bypasses database-native JSON validation, and may forfeit performance benefits offered by native JSON types in databases such as PostgreSQL.

Current Behavior

Migrations a5_001_add_actions_v3_table.py, a5_002_add_lifecycle_plans_table.py, and a5_003_spec_aligned_actions.py define JSON-bearing columns using sa.Text():

# From a5_001_add_actions_v3_table.py
sa.Column(
    "inputs_schema",
    sa.Text(),
    nullable=False,
    server_default="[]",
),

Expected Behavior

All columns that store JSON data should use sa.JSON() for consistency with the initial schema and to leverage database-specific features:

# From 001_initial_schema.py (correct pattern)
sa.Column("settings", sa.JSON(), nullable=True),

Acceptance Criteria

All JSON-bearing columns in a5_001, a5_002, and a5_003 use sa.JSON() instead of sa.Text()
A new Alembic migration is created (if needed) to alter existing column types in deployed databases, or the existing migrations are corrected if no deployments have occurred
All nox stages pass after the change
Coverage ≥ 97%

Supporting Information

Files affected:
- alembic/versions/a5_001_add_actions_v3_table.py
- alembic/versions/a5_002_add_lifecycle_plans_table.py
- alembic/versions/a5_003_spec_aligned_actions.py
Related issue: #7290 (Migration dependency chain inconsistency)
Severity: Low — unlikely to cause immediate failures, but reduces code quality and consistency
Category: consistency

TDD Note

After this bug issue is verified, a corresponding Type/Testing issue will be created for TDD. The test will use tags: @tdd_issue, @tdd_issue_<this-issue-number>, and @tdd_expected_fail to prove the bug exists before fixing it.

Subtasks

Audit all Alembic migration files for sa.Text() columns that store JSON data
Update a5_001_add_actions_v3_table.py — replace sa.Text() with sa.JSON() for JSON columns
Update a5_002_add_lifecycle_plans_table.py — replace sa.Text() with sa.JSON() for JSON columns
Update a5_003_spec_aligned_actions.py — replace sa.Text() with sa.JSON() for JSON columns
Determine if a corrective migration is needed for existing deployments; create one if so
Tests (Behave): Add/update scenarios verifying JSON column types in migration schema
Tests (Robot): Verify integration with real database confirms JSON column types
Verify coverage ≥ 97% via nox -s coverage_report
Run nox (all default sessions), fix any errors

Definition of Done

This issue is complete when:

All subtasks above are completed and checked off.
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly (fix(db): use sa.JSON() consistently for JSON columns in alembic migrations), followed by a blank line, then additional lines providing relevant details about the implementation.
The commit is pushed to the remote on the branch matching the Branch in Metadata exactly (fix/bug-consistency-alembic-json-storage).
The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.
All nox stages pass.
Coverage ≥ 97%.

Backlog note: This issue was discovered during autonomous operation
on milestone v3.2.0. 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: Bug Hunting | Agent: new-issue-creator

## Metadata - **Branch**: `fix/bug-consistency-alembic-json-storage` - **Commit Message**: `fix(db): use sa.JSON() consistently for JSON columns in alembic migrations` - **Milestone**: None (Backlog) - **Parent Epic**: N/A — orphan flagged below ## Background and Context The Alembic migrations `a5_001`, `a5_002`, and `a5_003` use `sa.Text()` to store JSON data, while the initial schema (`001_initial_schema.py`) uses `sa.JSON()`. This inconsistency is a code quality issue that reduces clarity, bypasses database-native JSON validation, and may forfeit performance benefits offered by native JSON types in databases such as PostgreSQL. ## Current Behavior Migrations `a5_001_add_actions_v3_table.py`, `a5_002_add_lifecycle_plans_table.py`, and `a5_003_spec_aligned_actions.py` define JSON-bearing columns using `sa.Text()`: ```python # From a5_001_add_actions_v3_table.py sa.Column( "inputs_schema", sa.Text(), nullable=False, server_default="[]", ), ``` ## Expected Behavior All columns that store JSON data should use `sa.JSON()` for consistency with the initial schema and to leverage database-specific features: ```python # From 001_initial_schema.py (correct pattern) sa.Column("settings", sa.JSON(), nullable=True), ``` ## Acceptance Criteria - [ ] All JSON-bearing columns in `a5_001`, `a5_002`, and `a5_003` use `sa.JSON()` instead of `sa.Text()` - [ ] A new Alembic migration is created (if needed) to alter existing column types in deployed databases, or the existing migrations are corrected if no deployments have occurred - [ ] All nox stages pass after the change - [ ] Coverage ≥ 97% ## Supporting Information - **Files affected**: - `alembic/versions/a5_001_add_actions_v3_table.py` - `alembic/versions/a5_002_add_lifecycle_plans_table.py` - `alembic/versions/a5_003_spec_aligned_actions.py` - **Related issue**: #7290 (Migration dependency chain inconsistency) - **Severity**: Low — unlikely to cause immediate failures, but reduces code quality and consistency - **Category**: consistency ### TDD Note After this bug issue is verified, a corresponding Type/Testing issue will be created for TDD. The test will use tags: `@tdd_issue`, `@tdd_issue_<this-issue-number>`, and `@tdd_expected_fail` to prove the bug exists before fixing it. ## Subtasks - [ ] Audit all Alembic migration files for `sa.Text()` columns that store JSON data - [ ] Update `a5_001_add_actions_v3_table.py` — replace `sa.Text()` with `sa.JSON()` for JSON columns - [ ] Update `a5_002_add_lifecycle_plans_table.py` — replace `sa.Text()` with `sa.JSON()` for JSON columns - [ ] Update `a5_003_spec_aligned_actions.py` — replace `sa.Text()` with `sa.JSON()` for JSON columns - [ ] Determine if a corrective migration is needed for existing deployments; create one if so - [ ] Tests (Behave): Add/update scenarios verifying JSON column types in migration schema - [ ] Tests (Robot): Verify integration with real database confirms JSON column types - [ ] Verify coverage ≥ 97% via `nox -s coverage_report` - [ ] Run `nox` (all default sessions), fix any errors ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly (`fix(db): use sa.JSON() consistently for JSON columns in alembic migrations`), followed by a blank line, then additional lines providing relevant details about the implementation. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly (`fix/bug-consistency-alembic-json-storage`). - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done. - All nox stages pass. - Coverage ≥ 97%. > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.2.0. 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: Bug Hunting | Agent: new-issue-creator

HAL9000 added the

State

Unverified

label

2026-04-12 05:47:31 +00:00

HAL9000 commented

2026-04-12 05:48:01 +00:00

Author

Owner

⚠️ Orphan Issue — Manual Linking Required

This issue was created by the new-issue-creator agent and could not be automatically linked to a parent Epic. A search of open Epics and Legendary issues did not find a dedicated "Bug Hunt" parent Epic that existing BUG-HUNT issues link to (confirmed by checking issues #7290, #7327, #7284, #7782 — none have active blocks or dependencies relationships to a parent Epic).

Action required by a human maintainer or Epic planner:

Identify or create the appropriate parent Epic for BUG-HUNT consistency issues
Link this issue as a child: this issue should block the parent Epic (child blocks parent)

Suggested parent candidates:

A "Bug Hunting" or "Code Quality" Epic covering consistency/migration issues
Related issue: #7290 (Migration dependency chain inconsistency — same migration file area)

Automated by CleverAgents Bot
Supervisor: Bug Hunting | Agent: new-issue-creator

⚠️ **Orphan Issue — Manual Linking Required** This issue was created by the `new-issue-creator` agent and could not be automatically linked to a parent Epic. A search of open Epics and Legendary issues did not find a dedicated "Bug Hunt" parent Epic that existing BUG-HUNT issues link to (confirmed by checking issues #7290, #7327, #7284, #7782 — none have active `blocks` or `dependencies` relationships to a parent Epic). **Action required by a human maintainer or Epic planner:** - Identify or create the appropriate parent Epic for BUG-HUNT consistency issues - Link this issue as a child: this issue should **block** the parent Epic (child blocks parent) **Suggested parent candidates:** - A "Bug Hunting" or "Code Quality" Epic covering consistency/migration issues - Related issue: #7290 (Migration dependency chain inconsistency — same migration file area) --- **Automated by CleverAgents Bot** Supervisor: Bug Hunting | Agent: new-issue-creator

freemo added the

labels

2026-04-12 18:33:28 +00:00

HAL9000 added

and removed

labels

2026-04-14 05:57:44 +00:00

HAL9000 commented

2026-04-14 05:57:44 +00:00

Author

Owner

✅ Verified — Consistency bug: inconsistent JSON storage in Alembic migrations. MoSCoW: Should-have. Priority: Medium.

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

✅ **Verified** — Consistency bug: inconsistent JSON storage in Alembic migrations. MoSCoW: Should-have. Priority: Medium. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor

HAL9000 commented

2026-04-14 06:11:03 +00:00

Author

Owner

✅ Verified — Consistency bug: inconsistent JSON storage in Alembic migrations. MoSCoW: Should-have. Priority: Medium.

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