cleveragents/cleveragents-core

Fork 3

BUG-HUNT: [dependency] Migration dependency chain inconsistency — a5_005 depends on b1_001 creating cross-workstream coupling without a merge migration #7290

New issue

Open

opened 2026-04-10 15:14:59 +00:00 by HAL9000 · 4 comments

HAL9000 commented

2026-04-10 15:14:59 +00:00

Owner

Bug Report: [dependency] Migration Dependency Chain Inconsistency in `a5_005_rebaseline_plan_phases`

Severity Assessment

Impact: Migration failures, schema drift, and deployment failures when migrations run out of order. Any deployment pipeline that applies migrations in workstream order (a5_ before b1_) will fail because a5_005 cannot be applied until b1_001_resource_registry exists. This creates a hidden cross-workstream coupling that violates the milestone-based naming convention and makes the migration graph harder to reason about.
Likelihood: Medium — occurs during complex branch merges and deployment scenarios where workstream ordering is assumed from filename prefixes.
Priority: Medium

Location

File: alembic/versions/a5_005_rebaseline_plan_phases.py
Lines: 32

Description

a5_005_rebaseline_plan_phases.py declares down_revision = "b1_001_resource_registry", meaning the a5_ series (actions/plan lifecycle) directly depends on the b1_ series (resource registry). This creates a cross-workstream dependency without a proper merge migration.

The b1_001_resource_registry_tables.py migration itself revises a5_004_spec_aligned_plans, so the actual chain is:

a5_004_spec_aligned_plans
    └── b1_001_resource_registry   (b1_ workstream)
            └── a5_005_rebaseline_plan_phases  (back to a5_ workstream!)

This violates the milestone-based migration naming convention where prefixes (a5_, b1_, b0_, c1_, etc.) are expected to reflect workstream/milestone groupings. A developer reading the filenames would expect a5_005 to follow a5_004, not b1_001.

Evidence

# In alembic/versions/a5_005_rebaseline_plan_phases.py, line 32:
down_revision: str | Sequence[str] | None = "b1_001_resource_registry"

The b1_001_resource_registry_tables.py file confirms the revision ID:

# Revision ID: b1_001_resource_registry
# Revises: a5_004_spec_aligned_plans

So the actual dependency chain is: a5_004 → b1_001 → a5_005, which is a cross-workstream dependency without a merge migration.

Expected Behavior

According to the specification, migration naming follows milestone-based prefixes (m4_, m5_, m6_) and feature-based prefixes (a5_, b0_, c1_). Cross-workstream dependencies should use a merge migration (e.g., a7_002_merge_heads.py pattern already used in the codebase) to explicitly document the convergence point. The a5_005 migration should either:

Follow a5_004 directly (if the b1_ dependency is not actually required), or
Use a merge migration that explicitly merges the a5_ and b1_ heads before continuing.

Actual Behavior

a5_005_rebaseline_plan_phases.py directly depends on b1_001_resource_registry, creating an implicit cross-workstream dependency. Any tool or developer that infers migration execution order from filename prefixes will get the wrong order. The a5_ series appears to be self-contained but silently requires the b1_ workstream to have run first.

Suggested Fix

Option 1 — Create a merge migration (preferred, matches existing pattern):

# New file: a5_005_merge_a5_and_b1_heads.py
revision = "a5_005_merge_a5_and_b1_heads"
down_revision = ("a5_004_spec_aligned_plans", "b1_001_resource_registry")
branch_labels = None
depends_on = None
# upgrade/downgrade: pass (merge only)

Then update a5_005_rebaseline_plan_phases.py to revise the merge migration.

Option 2 — Restructure the dependency to maintain workstream isolation if b1_001 is not actually a prerequisite for the plan phase rebaseline.

Option 3 — Rename a5_005 to a milestone-neutral name (e.g., m5_xxx) that reflects its cross-workstream nature.

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.

Metadata

Branch: bugfix/migration-a5-005-cross-workstream-dependency
Commit Message: fix(database): add merge migration to resolve cross-workstream a5_005→b1_001 dependency chain
Milestone: (none — backlog)
Parent Epic: (see orphan note below)

Subtasks

Audit the full migration dependency graph to confirm the cross-workstream coupling
Determine whether a5_005 genuinely requires b1_001 or if the dependency is incidental
Create a merge migration (or restructure dependency) to make the cross-workstream coupling explicit
Update a5_005_rebaseline_plan_phases.py down_revision to reference the merge migration
Verify alembic history and alembic heads show a clean, single-head graph after the fix
Verify alembic upgrade head and alembic downgrade base succeed on a fresh database
Write BDD scenario proving the migration chain is consistent (no cross-workstream implicit deps)

Definition of Done

Migration dependency graph has no implicit cross-workstream dependencies
alembic check passes with no detected inconsistencies
alembic upgrade head succeeds on a fresh SQLite database
alembic downgrade base succeeds without errors
BDD scenario with @tdd_issue and @tdd_issue_<N> tags exists and passes
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: Acting on behalf of: Bug Hunter | Agent: new-issue-creator

## Bug Report: [dependency] Migration Dependency Chain Inconsistency in `a5_005_rebaseline_plan_phases` ### Severity Assessment - **Impact**: Migration failures, schema drift, and deployment failures when migrations run out of order. Any deployment pipeline that applies migrations in workstream order (a5_ before b1_) will fail because `a5_005` cannot be applied until `b1_001_resource_registry` exists. This creates a hidden cross-workstream coupling that violates the milestone-based naming convention and makes the migration graph harder to reason about. - **Likelihood**: Medium — occurs during complex branch merges and deployment scenarios where workstream ordering is assumed from filename prefixes. - **Priority**: Medium ### Location - **File**: `alembic/versions/a5_005_rebaseline_plan_phases.py` - **Lines**: 32 ### Description `a5_005_rebaseline_plan_phases.py` declares `down_revision = "b1_001_resource_registry"`, meaning the `a5_` series (actions/plan lifecycle) directly depends on the `b1_` series (resource registry). This creates a cross-workstream dependency without a proper merge migration. The `b1_001_resource_registry_tables.py` migration itself revises `a5_004_spec_aligned_plans`, so the actual chain is: ``` a5_004_spec_aligned_plans └── b1_001_resource_registry (b1_ workstream) └── a5_005_rebaseline_plan_phases (back to a5_ workstream!) ``` This violates the milestone-based migration naming convention where prefixes (`a5_`, `b1_`, `b0_`, `c1_`, etc.) are expected to reflect workstream/milestone groupings. A developer reading the filenames would expect `a5_005` to follow `a5_004`, not `b1_001`. ### Evidence ```python # In alembic/versions/a5_005_rebaseline_plan_phases.py, line 32: down_revision: str | Sequence[str] | None = "b1_001_resource_registry" ``` The `b1_001_resource_registry_tables.py` file confirms the revision ID: ```python # Revision ID: b1_001_resource_registry # Revises: a5_004_spec_aligned_plans ``` So the actual dependency chain is: `a5_004 → b1_001 → a5_005`, which is a cross-workstream dependency without a merge migration. ### Expected Behavior According to the specification, migration naming follows milestone-based prefixes (`m4_`, `m5_`, `m6_`) and feature-based prefixes (`a5_`, `b0_`, `c1_`). Cross-workstream dependencies should use a merge migration (e.g., `a7_002_merge_heads.py` pattern already used in the codebase) to explicitly document the convergence point. The `a5_005` migration should either: 1. Follow `a5_004` directly (if the b1_ dependency is not actually required), or 2. Use a merge migration that explicitly merges the `a5_` and `b1_` heads before continuing. ### Actual Behavior `a5_005_rebaseline_plan_phases.py` directly depends on `b1_001_resource_registry`, creating an implicit cross-workstream dependency. Any tool or developer that infers migration execution order from filename prefixes will get the wrong order. The `a5_` series appears to be self-contained but silently requires the `b1_` workstream to have run first. ### Suggested Fix Option 1 — **Create a merge migration** (preferred, matches existing pattern): ```python # New file: a5_005_merge_a5_and_b1_heads.py revision = "a5_005_merge_a5_and_b1_heads" down_revision = ("a5_004_spec_aligned_plans", "b1_001_resource_registry") branch_labels = None depends_on = None # upgrade/downgrade: pass (merge only) ``` Then update `a5_005_rebaseline_plan_phases.py` to revise the merge migration. Option 2 — **Restructure the dependency** to maintain workstream isolation if `b1_001` is not actually a prerequisite for the plan phase rebaseline. Option 3 — **Rename** `a5_005` to a milestone-neutral name (e.g., `m5_xxx`) that reflects its cross-workstream nature. ### Category dependency ### 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. --- ## Metadata - **Branch**: `bugfix/migration-a5-005-cross-workstream-dependency` - **Commit Message**: `fix(database): add merge migration to resolve cross-workstream a5_005→b1_001 dependency chain` - **Milestone**: *(none — backlog)* - **Parent Epic**: *(see orphan note below)* ## Subtasks - [ ] Audit the full migration dependency graph to confirm the cross-workstream coupling - [ ] Determine whether `a5_005` genuinely requires `b1_001` or if the dependency is incidental - [ ] Create a merge migration (or restructure dependency) to make the cross-workstream coupling explicit - [ ] Update `a5_005_rebaseline_plan_phases.py` `down_revision` to reference the merge migration - [ ] Verify `alembic history` and `alembic heads` show a clean, single-head graph after the fix - [ ] Verify `alembic upgrade head` and `alembic downgrade base` succeed on a fresh database - [ ] Write BDD scenario proving the migration chain is consistent (no cross-workstream implicit deps) ## Definition of Done - [ ] Migration dependency graph has no implicit cross-workstream dependencies - [ ] `alembic check` passes with no detected inconsistencies - [ ] `alembic upgrade head` succeeds on a fresh SQLite database - [ ] `alembic downgrade base` succeeds without errors - [ ] BDD scenario with `@tdd_issue` and `@tdd_issue_<N>` tags exists and passes - [ ] 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: Acting on behalf of: Bug Hunter | Agent: new-issue-creator

HAL9000 added the

labels

2026-04-10 15:16:24 +00:00

HAL9000 commented

2026-04-10 15:16:44 +00:00

Author

Owner

⚠️ Orphan Issue — Needs Manual Parent Epic Linking

This issue was created without a parent Epic because no suitable migration infrastructure Epic was found in the open issues. Similar migration bug issues (#6648, #6652, #6655, #6656) are also orphans with no parent Epic linked.

A maintainer should either:

Link this issue to an existing Epic that covers Alembic migration infrastructure quality (if one exists), or
Create a new Epic for "Migration Infrastructure Quality" and link this issue (and the related migration bugs) as children.

Per CONTRIBUTING.md, orphan issues are not permitted. This issue needs a parent Epic before it can be moved to State/Verified.

Related migration bug issues (also potentially orphaned):

#6648 — a5_005 downgrade crashes with CHECK constraint violation
#6652 — m4_003 has out-of-order naming
#6655 — d0_001 downgrade drops tables without dropping named indexes
#6656 — c1_001 and c4_001 docstring Revises: fields are wrong

Automated by CleverAgents Bot
Supervisor: Acting on behalf of: Bug Hunter | Agent: new-issue-creator

⚠️ **Orphan Issue — Needs Manual Parent Epic Linking** This issue was created without a parent Epic because no suitable migration infrastructure Epic was found in the open issues. Similar migration bug issues (#6648, #6652, #6655, #6656) are also orphans with no parent Epic linked. A maintainer should either: 1. Link this issue to an existing Epic that covers Alembic migration infrastructure quality (if one exists), or 2. Create a new Epic for "Migration Infrastructure Quality" and link this issue (and the related migration bugs) as children. Per CONTRIBUTING.md, orphan issues are not permitted. This issue needs a parent Epic before it can be moved to `State/Verified`. **Related migration bug issues (also potentially orphaned):** - #6648 — a5_005 downgrade crashes with CHECK constraint violation - #6652 — m4_003 has out-of-order naming - #6655 — d0_001 downgrade drops tables without dropping named indexes - #6656 — c1_001 and c4_001 docstring Revises: fields are wrong --- **Automated by CleverAgents Bot** Supervisor: Acting on behalf of: Bug Hunter | Agent: new-issue-creator

HAL9000 referenced this issue

2026-04-10 15:30:52 +00:00

[AUTO-UAT-POOL] UAT Testing Report (Cycle 120) #7291

HAL9000 referenced this issue

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

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

HAL9000 referenced this issue

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

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

HAL9000 referenced this issue

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

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

HAL9000 referenced this issue

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

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

HAL9000 added

and removed

labels

2026-04-14 06:24:19 +00:00

HAL9000 commented

2026-04-14 06:24:19 +00:00

Author

Owner

✅ Verified — Migration dependency bug: cross-workstream coupling without merge migration. MoSCoW: Should-have. Priority: Medium.

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

✅ **Verified** — Migration dependency bug: cross-workstream coupling without merge migration. MoSCoW: Should-have. Priority: Medium. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor

HAL9000 commented

2026-04-14 06:29:57 +00:00

Author

Owner

✅ Verified — Migration dependency bug: cross-workstream coupling without merge migration. MoSCoW: Should-have. Priority: Medium.

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