BUG-HUNT: [migration] m4_003_plan_env_columns has out-of-order naming — depends on m6_005 (created later) making file-order-based tooling misleading #6652

New issue

Open

opened 2026-04-09 22:46:06 +00:00 by HAL9000 · 0 comments

HAL9000 commented

2026-04-09 22:46:06 +00:00

Owner

Bug Report: [migration] Out-of-Order Migration Naming: `m4_003` Depends on `m6_005`

Severity Assessment

Impact: Any developer, CI script, or tool that infers migration execution order from filename prefixes (which is common) will get the wrong order. m4_003 will appear to run before m6_003, m6_004, m6_005, etc. — but the actual Alembic execution order is m6_005 → m4_003. This breaks assumptions in documentation, code reviews, migration auditing tools, and any script that processes migrations by filename glob (m4_*.py, m6_*.py).
Likelihood: High — file-prefix ordering is a common developer assumption when navigating Alembic migrations.
Priority: Medium

Location

File: alembic/versions/m4_003_plan_env_columns.py
Lines: 1–17 (header docstring and down_revision)

Description

m4_003_plan_env_columns.py has the migration prefix m4_003 but was created on 2026-03-16 and depends on m6_005_profile_guards_json (created on 2026-03-13):

# m4_003_plan_env_columns.py
revision: str = "m4_003_plan_env_columns"
down_revision: str | Sequence[str] | None = "m6_005_profile_guards_json"
# Create Date: 2026-03-16 00:00:00

The full dependency chain demonstrates that m4_003 runs after the entire m6_001 through m6_005 chain:

... → m6_001 → m4_002 → m4_001_decision → d0_002 → ... → m6_002 → m6_003 → m7_001 → m6_004_resource → m6_004_container → m6_005 → m4_003 → m5_001 / m8_001_align / m8_001_correction → m8_002 → m6_006 → m9_001 → m9_002 → a5_006

The m4_003 file prefix m4 numerically precedes m5, m6, m7, m8, m9 — yet it is actually the second-to-last leaf before the final merge. This means:

ls alembic/versions/m4*.py shows m4_001_concurrency_locks, m4_001_decision_tables, m4_002_skill_flattened_tools, m4_003_plan_env_columns — appearing to be a cohesive early batch of migrations, when in fact m4_003 runs much later than the others.
The docstring Revises: m6_005_profile_guards_json (in the Create Date comment) partially reveals this, but only if read carefully.
Standard Alembic history visualization (alembic history) does show the correct order, but file-level grep/audit tools do not.

This is the result of a migration being added retroactively with a lower-numbered prefix rather than a new prefix that reflects its actual position in the chain.

Evidence

# File order implies m4_003 runs early:
$ ls alembic/versions/m*.py | head -8
m4_001_concurrency_locks.py
m4_001_decision_tables.py
m4_002_skill_flattened_tools.py
m4_003_plan_env_columns.py    # ← appears to be in m4 batch
m5_001_rename_automation_profile_fields.py
m6_001_checkpoint_metadata_table.py
...

# Actual chain shows m4_003 depends on m6_005:
$ grep "down_revision" alembic/versions/m4_003_plan_env_columns.py
down_revision: str | Sequence[str] | None = "m6_005_profile_guards_json"

Expected Behavior

Migrations should be named with a prefix that reflects their actual chronological/topological position in the chain. A migration that depends on m6_005 should have a prefix of m6_006 or higher (e.g., m6_006_plan_env_columns.py), not m4_003.

Actual Behavior

m4_003_plan_env_columns.py runs after the entire m6_001–m6_005 chain, but its filename prefix suggests it is part of the m4 batch.

Suggested Fix

Rename m4_003_plan_env_columns.py to a prefix that reflects its actual position — for example m6_006a_plan_env_columns.py or simply the next available prefix after m6_005. The revision and down_revision variables within the file do not need to change (they are the canonical identifiers), but the filename should match the chain position for human navigability.

As a minimum, add a prominent warning comment to the file header:

"""Add execution_environment and execution_env_priority columns to v3_plans.

WARNING: Despite the m4_ prefix, this migration runs AFTER the entire m6_001–m6_005
chain. It was added retroactively. The actual execution order is:
  ... m6_005_profile_guards_json → m4_003_plan_env_columns (this file) → ...

Do not infer execution order from filename prefixes for this migration.
"""

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.

Automated by CleverAgents Bot
Supervisor: Bug Hunting | Agent: bug-hunter

## Bug Report: [migration] Out-of-Order Migration Naming: `m4_003` Depends on `m6_005` ### Severity Assessment - **Impact**: Any developer, CI script, or tool that infers migration execution order from filename prefixes (which is common) will get the wrong order. `m4_003` will appear to run before `m6_003`, `m6_004`, `m6_005`, etc. — but the actual Alembic execution order is `m6_005 → m4_003`. This breaks assumptions in documentation, code reviews, migration auditing tools, and any script that processes migrations by filename glob (`m4_*.py`, `m6_*.py`). - **Likelihood**: High — file-prefix ordering is a common developer assumption when navigating Alembic migrations. - **Priority**: Medium ### Location - **File**: `alembic/versions/m4_003_plan_env_columns.py` - **Lines**: 1–17 (header docstring and `down_revision`) ### Description `m4_003_plan_env_columns.py` has the migration prefix `m4_003` but was created on **2026-03-16** and depends on `m6_005_profile_guards_json` (created on **2026-03-13**): ```python # m4_003_plan_env_columns.py revision: str = "m4_003_plan_env_columns" down_revision: str | Sequence[str] | None = "m6_005_profile_guards_json" # Create Date: 2026-03-16 00:00:00 ``` The full dependency chain demonstrates that `m4_003` runs **after** the entire `m6_001` through `m6_005` chain: ``` ... → m6_001 → m4_002 → m4_001_decision → d0_002 → ... → m6_002 → m6_003 → m7_001 → m6_004_resource → m6_004_container → m6_005 → m4_003 → m5_001 / m8_001_align / m8_001_correction → m8_002 → m6_006 → m9_001 → m9_002 → a5_006 ``` The `m4_003` file prefix `m4` numerically precedes `m5`, `m6`, `m7`, `m8`, `m9` — yet it is actually the second-to-last leaf before the final merge. This means: 1. **`ls alembic/versions/m4*.py`** shows `m4_001_concurrency_locks`, `m4_001_decision_tables`, `m4_002_skill_flattened_tools`, `m4_003_plan_env_columns` — appearing to be a cohesive early batch of migrations, when in fact `m4_003` runs much later than the others. 2. The docstring `Revises: m6_005_profile_guards_json` (in the `Create Date` comment) partially reveals this, but only if read carefully. 3. Standard Alembic history visualization (`alembic history`) does show the correct order, but file-level grep/audit tools do not. This is the result of a migration being added retroactively with a lower-numbered prefix rather than a new prefix that reflects its actual position in the chain. ### Evidence ```bash # File order implies m4_003 runs early: $ ls alembic/versions/m*.py | head -8 m4_001_concurrency_locks.py m4_001_decision_tables.py m4_002_skill_flattened_tools.py m4_003_plan_env_columns.py # ← appears to be in m4 batch m5_001_rename_automation_profile_fields.py m6_001_checkpoint_metadata_table.py ... # Actual chain shows m4_003 depends on m6_005: $ grep "down_revision" alembic/versions/m4_003_plan_env_columns.py down_revision: str | Sequence[str] | None = "m6_005_profile_guards_json" ``` ### Expected Behavior Migrations should be named with a prefix that reflects their actual chronological/topological position in the chain. A migration that depends on `m6_005` should have a prefix of `m6_006` or higher (e.g., `m6_006_plan_env_columns.py`), not `m4_003`. ### Actual Behavior `m4_003_plan_env_columns.py` runs after the entire `m6_001`–`m6_005` chain, but its filename prefix suggests it is part of the `m4` batch. ### Suggested Fix Rename `m4_003_plan_env_columns.py` to a prefix that reflects its actual position — for example `m6_006a_plan_env_columns.py` or simply the next available prefix after `m6_005`. The `revision` and `down_revision` variables within the file do not need to change (they are the canonical identifiers), but the filename should match the chain position for human navigability. As a minimum, add a prominent warning comment to the file header: ```python """Add execution_environment and execution_env_priority columns to v3_plans. WARNING: Despite the m4_ prefix, this migration runs AFTER the entire m6_001–m6_005 chain. It was added retroactively. The actual execution order is: ... m6_005_profile_guards_json → m4_003_plan_env_columns (this file) → ... Do not infer execution order from filename prefixes for this migration. """ ``` ### Category `consistency` / `migration` ### 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. --- **Automated by CleverAgents Bot** Supervisor: Bug Hunting | Agent: bug-hunter

HAL9000 added the

labels

2026-04-09 23:00:58 +00:00

HAL9000 added this to the v3.2.0 milestone

2026-04-09 23:04:02 +00:00

HAL9000 referenced this issue