cleveragents/cleveragents-core

Fork 3

BUG-HUNT: [alembic] Empty merge migrations in alembic/versions #7925

New issue

Open

opened 2026-04-12 07:48:24 +00:00 by HAL9000 · 2 comments

HAL9000 commented

2026-04-12 07:48:24 +00:00

Owner

Metadata

Branch: bugfix/alembic-empty-merge-migrations
Commit Message: fix(database): investigate and document empty merge migrations in alembic/versions
Milestone: None (Backlog)
Parent Epic: (see orphan note below)

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.

Background and Context

Several merge migration files in alembic/versions/ have empty upgrade() and downgrade() functions. Merge migrations in Alembic are used to reconcile multiple migration heads into a single linear history. While it is valid for merge migrations to be no-ops (they exist purely to unify the DAG), the presence of multiple such files warrants investigation to confirm they are intentional and correctly structured.

If any of these empty merge migrations are the result of an incomplete or incorrect merge, they could lead to an inconsistent database schema, causing runtime errors or data corruption.

Current Behavior

The following merge migration files contain empty upgrade() and downgrade() functions:

alembic/versions/71cd40eb661f_merge_resource_links_and_automation_.py
alembic/versions/a7_002_merge_heads.py
alembic/versions/c0_002_merge_skill_registry_head.py
alembic/versions/d0_002_merge_changeset_and_locks.py
alembic/versions/m6_002_merge_safety_and_checkpoint.py
alembic/versions/m8_002_merge_profile_rename_and_corrections.py

Example from 71cd40eb661f_merge_resource_links_and_automation_.py:

def upgrade() -> None:
    """Upgrade schema."""
    pass


def downgrade() -> None:
    """Downgrade schema."""
    pass

Expected Behavior

Each merge migration should be verified as intentionally empty (i.e., it exists only to unify divergent migration heads with no schema changes required). If any are not intentional no-ops, they must be corrected with the appropriate schema changes. All merge migrations should have accurate Revises: docstring fields and correct down_revision tuples pointing to the branches they merge.

Acceptance Criteria

Each of the six empty merge migrations is audited to confirm it is intentionally a no-op
Each merge migration's down_revision tuple is verified to correctly reference the two (or more) branch heads it merges
Each merge migration's Revises: docstring field matches the actual down_revision value
If any merge migration is found to be incorrect, a follow-up fix migration is created
alembic heads reports a single head after all migrations are applied
alembic upgrade head and alembic downgrade base complete without errors on a fresh database
All nox stages pass
Coverage >= 97%

Supporting Information

Related issues: #7290 (cross-workstream dependency chain inconsistency), #7283 (missing ondelete actions), #6656 (wrong Revises: docstrings), #6655 (downgrade symmetry violation), #6652 (out-of-order naming), #6648 (downgrade crash), #6647 (duplicate constraints)
Alembic merge migrations documentation: https://alembic.sqlalchemy.org/en/latest/branches.html#merging-branches
Category: spec-alignment

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 71cd40eb661f_merge_resource_links_and_automation_.py — verify down_revision tuple and confirm intentional no-op
Audit a7_002_merge_heads.py — verify down_revision tuple and confirm intentional no-op
Audit c0_002_merge_skill_registry_head.py — verify down_revision tuple and confirm intentional no-op
Audit d0_002_merge_changeset_and_locks.py — verify down_revision tuple and confirm intentional no-op
Audit m6_002_merge_safety_and_checkpoint.py — verify down_revision tuple and confirm intentional no-op
Audit m8_002_merge_profile_rename_and_corrections.py — verify down_revision tuple and confirm intentional no-op
Run alembic heads to confirm single head after all migrations applied
Run alembic upgrade head and alembic downgrade base on a fresh database
Create follow-up fix migrations for any incorrect merge migrations found
Tests (Behave): Add scenarios verifying merge migration graph integrity
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, 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.
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%

⚠️ Orphan note: No parent Epic for Alembic migration correctness currently exists in the backlog. This issue requires manual linking to an appropriate Epic by a maintainer. Related alembic migration bugs: #7290, #7283, #6656, #6655, #6652, #6648, #6647.

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

## Metadata - **Branch**: `bugfix/alembic-empty-merge-migrations` - **Commit Message**: `fix(database): investigate and document empty merge migrations in alembic/versions` - **Milestone**: None (Backlog) - **Parent Epic**: *(see orphan note below)* > **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. --- ## Background and Context Several merge migration files in `alembic/versions/` have empty `upgrade()` and `downgrade()` functions. Merge migrations in Alembic are used to reconcile multiple migration heads into a single linear history. While it is valid for merge migrations to be no-ops (they exist purely to unify the DAG), the presence of multiple such files warrants investigation to confirm they are intentional and correctly structured. If any of these empty merge migrations are the result of an incomplete or incorrect merge, they could lead to an inconsistent database schema, causing runtime errors or data corruption. ## Current Behavior The following merge migration files contain empty `upgrade()` and `downgrade()` functions: - `alembic/versions/71cd40eb661f_merge_resource_links_and_automation_.py` - `alembic/versions/a7_002_merge_heads.py` - `alembic/versions/c0_002_merge_skill_registry_head.py` - `alembic/versions/d0_002_merge_changeset_and_locks.py` - `alembic/versions/m6_002_merge_safety_and_checkpoint.py` - `alembic/versions/m8_002_merge_profile_rename_and_corrections.py` Example from `71cd40eb661f_merge_resource_links_and_automation_.py`: ```python def upgrade() -> None: """Upgrade schema.""" pass def downgrade() -> None: """Downgrade schema.""" pass ``` ## Expected Behavior Each merge migration should be verified as intentionally empty (i.e., it exists only to unify divergent migration heads with no schema changes required). If any are not intentional no-ops, they must be corrected with the appropriate schema changes. All merge migrations should have accurate `Revises:` docstring fields and correct `down_revision` tuples pointing to the branches they merge. ## Acceptance Criteria - [ ] Each of the six empty merge migrations is audited to confirm it is intentionally a no-op - [ ] Each merge migration's `down_revision` tuple is verified to correctly reference the two (or more) branch heads it merges - [ ] Each merge migration's `Revises:` docstring field matches the actual `down_revision` value - [ ] If any merge migration is found to be incorrect, a follow-up fix migration is created - [ ] `alembic heads` reports a single head after all migrations are applied - [ ] `alembic upgrade head` and `alembic downgrade base` complete without errors on a fresh database - [ ] All nox stages pass - [ ] Coverage >= 97% ## Supporting Information - Related issues: #7290 (cross-workstream dependency chain inconsistency), #7283 (missing ondelete actions), #6656 (wrong `Revises:` docstrings), #6655 (downgrade symmetry violation), #6652 (out-of-order naming), #6648 (downgrade crash), #6647 (duplicate constraints) - Alembic merge migrations documentation: https://alembic.sqlalchemy.org/en/latest/branches.html#merging-branches - Category: spec-alignment ### 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 `71cd40eb661f_merge_resource_links_and_automation_.py` — verify `down_revision` tuple and confirm intentional no-op - [ ] Audit `a7_002_merge_heads.py` — verify `down_revision` tuple and confirm intentional no-op - [ ] Audit `c0_002_merge_skill_registry_head.py` — verify `down_revision` tuple and confirm intentional no-op - [ ] Audit `d0_002_merge_changeset_and_locks.py` — verify `down_revision` tuple and confirm intentional no-op - [ ] Audit `m6_002_merge_safety_and_checkpoint.py` — verify `down_revision` tuple and confirm intentional no-op - [ ] Audit `m8_002_merge_profile_rename_and_corrections.py` — verify `down_revision` tuple and confirm intentional no-op - [ ] Run `alembic heads` to confirm single head after all migrations applied - [ ] Run `alembic upgrade head` and `alembic downgrade base` on a fresh database - [ ] Create follow-up fix migrations for any incorrect merge migrations found - [ ] Tests (Behave): Add scenarios verifying merge migration graph integrity - [ ] 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, 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. - 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% --- > ⚠️ **Orphan note:** No parent Epic for Alembic migration correctness currently exists in the backlog. This issue requires manual linking to an appropriate Epic by a maintainer. Related alembic migration bugs: #7290, #7283, #6656, #6655, #6652, #6648, #6647. --- **Automated by CleverAgents Bot** Supervisor: Bug Hunting | Agent: new-issue-creator

HAL9000 referenced this issue

2026-04-12 07:52:48 +00:00

[AUTO-WDOG] Watchdog Status (Cycle 5) #7928

HAL9000 added the

labels

2026-04-12 07:54:37 +00:00

HAL9000 commented

2026-04-12 07:56:07 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: Low — Empty merge migrations are likely intentional no-ops (Alembic uses them to unify divergent migration heads). However, they should be audited to confirm correctness.
Milestone: None (Backlog) — as noted in the issue itself, this is a backlog item that doesn't block milestone completion
Story Points: 3 — M — Requires auditing 6 migration files, verifying down_revision tuples, running alembic commands
MoSCoW: Could Have — database migration correctness is important but this is an audit/verification task, not a known bug
Parent Epic: None identified (orphan as noted in the issue)

Rationale: Empty merge migrations are a normal Alembic pattern for unifying divergent migration heads. The issue correctly identifies that these need auditing, but they're likely intentional. This is a "Could Have" verification task for the backlog.

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

Issue triaged by project owner: - **State**: Verified - **Priority**: Low — Empty merge migrations are likely intentional no-ops (Alembic uses them to unify divergent migration heads). However, they should be audited to confirm correctness. - **Milestone**: None (Backlog) — as noted in the issue itself, this is a backlog item that doesn't block milestone completion - **Story Points**: 3 — M — Requires auditing 6 migration files, verifying down_revision tuples, running alembic commands - **MoSCoW**: Could Have — database migration correctness is important but this is an audit/verification task, not a known bug - **Parent Epic**: None identified (orphan as noted in the issue) **Rationale**: Empty merge migrations are a normal Alembic pattern for unifying divergent migration heads. The issue correctly identifies that these need auditing, but they're likely intentional. This is a "Could Have" verification task for the backlog. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor

HAL9000 commented

2026-04-12 07:56:32 +00:00

Author

Owner

⚠️ Orphan Issue — Manual Linking Required

This issue has no parent Epic. Per CONTRIBUTING.md, every non-Epic/non-Legendary issue must be linked to at least one parent Epic using Forgejo's dependency system (child blocks parent).

No dedicated Alembic migration correctness Epic currently exists in the backlog. A maintainer should either:

Create a new Epic for "Alembic Migration Correctness & Graph Integrity" and link this issue as a child, OR
Link this issue to an existing appropriate Epic (e.g., a database integrity Epic if one is created)

Related alembic migration bugs that may benefit from the same parent Epic:

#7290 — cross-workstream dependency chain inconsistency
#7283 — missing ondelete actions in initial schema migration
#6656 — wrong Revises: docstring fields
#6655 — downgrade drops tables without dropping named indexes
#6652 — out-of-order naming in m4_003
#6648 — a5_005 downgrade crashes with CHECK constraint violation
#6647 — a5_006 re-creates constraints already defined in a5_003

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

⚠️ **Orphan Issue — Manual Linking Required** This issue has no parent Epic. Per CONTRIBUTING.md, every non-Epic/non-Legendary issue **must** be linked to at least one parent Epic using Forgejo's dependency system (child **blocks** parent). No dedicated Alembic migration correctness Epic currently exists in the backlog. A maintainer should either: 1. **Create a new Epic** for "Alembic Migration Correctness & Graph Integrity" and link this issue as a child, OR 2. **Link this issue** to an existing appropriate Epic (e.g., a database integrity Epic if one is created) Related alembic migration bugs that may benefit from the same parent Epic: - #7290 — cross-workstream dependency chain inconsistency - #7283 — missing ondelete actions in initial schema migration - #6656 — wrong `Revises:` docstring fields - #6655 — downgrade drops tables without dropping named indexes - #6652 — out-of-order naming in m4_003 - #6648 — a5_005 downgrade crashes with CHECK constraint violation - #6647 — a5_006 re-creates constraints already defined in a5_003 --- **Automated by CleverAgents Bot** Supervisor: Bug Hunting | Agent: new-issue-creator

HAL9000 added

and removed

labels