BUG-HUNT: [migration] c1_001 and c4_001 docstring `Revises:` fields are wrong — misleads developers tracing migration lineage #6656

New issue

Open

opened 2026-04-09 22:47:49 +00:00 by HAL9000 · 0 comments

HAL9000 commented

2026-04-09 22:47:49 +00:00

Owner

Bug Report: [migration] Stale `Revises:` Docstring Fields in `c1_001` and `c4_001`

Severity Assessment

Impact: Developers using the Revises: comment in migration headers to quickly trace migration lineage will get incorrect information. This is especially dangerous when cherry-picking migrations, performing manual rollbacks, or explaining the migration chain in incident postmortems. The discrepancy between docstring and actual down_revision creates confusion and erodes trust in migration documentation.
Likelihood: Medium — most developers rely on alembic history for chain tracing, but some tooling (custom scripts, grep-based audits, changelogs) parses the docstring Revises: field.
Priority: Medium

Location

File 1: alembic/versions/c1_001_tool_registry_tables.py — Lines 1–17
File 2: alembic/versions/c4_001_safety_profile_column.py — Lines 1–17

Description

Both migration files have a Revises: entry in their module docstring that does not match the actual down_revision variable — the canonical field that Alembic uses to determine migration order.

`c1_001_tool_registry_tables.py`

"""Add tool registry tables (tools, tool_resource_bindings, validation_attachments).

...
Revision ID: c1_001_tool_registry
Revises: b1_001_resource_registry      # ← DOCSTRING SAYS THIS
Create Date: 2026-02-14 12:00:00
"""
...
revision: str = "c1_001_tool_registry"
down_revision: str | Sequence[str] | None = "b0_001_projects"   # ← ACTUAL PARENT

The docstring claims the parent is b1_001_resource_registry, but the actual parent is b0_001_projects. Alembic uses down_revision (the code variable), not the docstring comment. So the migration runs correctly, but the comment is wrong.

`c4_001_safety_profile_column.py`

"""Add safety_profile_json column to actions table.

...
Revision ID: c4_001_safety_profile_column
Revises: 71cd40eb661f                   # ← DOCSTRING SAYS THIS
Create Date: 2026-02-26 00:00:00
"""
...
revision: str = "c4_001_safety_profile_column"
down_revision: str | Sequence[str] | None = "c0_002_merge_skill_registry"  # ← ACTUAL PARENT

The docstring claims the parent is 71cd40eb661f (the old merge-resource-links migration), but the actual parent is c0_002_merge_skill_registry.

Both are likely a result of the Revises: line being written with an earlier draft value and not updated after the migration was rebased or repointed.

Evidence

$ grep "Revises:\|down_revision" alembic/versions/c1_001_tool_registry_tables.py
Revises: b1_001_resource_registry
down_revision: str | Sequence[str] | None = "b0_001_projects"

$ grep "Revises:\|down_revision" alembic/versions/c4_001_safety_profile_column.py
Revises: 71cd40eb661f
down_revision: str | Sequence[str] | None = "c0_002_merge_skill_registry"

Expected Behavior

The Revises: docstring field should match the down_revision variable exactly. By convention, Alembic-generated migrations always keep these in sync.

Actual Behavior

Revises: in the docstring refers to stale/incorrect parent revision IDs that no longer reflect the actual down_revision.

Suggested Fix

c1_001_tool_registry_tables.py — change:

Revises: b1_001_resource_registry

to:

Revises: b0_001_projects

c4_001_safety_profile_column.py — change:

Revises: 71cd40eb661f

to:

Revises: c0_002_merge_skill_registry

Consider adding a CI check (e.g., a custom alembic check script or pre-commit hook) that validates the docstring Revises: field matches down_revision for all migrations.

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] Stale `Revises:` Docstring Fields in `c1_001` and `c4_001` ### Severity Assessment - **Impact**: Developers using the `Revises:` comment in migration headers to quickly trace migration lineage will get incorrect information. This is especially dangerous when cherry-picking migrations, performing manual rollbacks, or explaining the migration chain in incident postmortems. The discrepancy between docstring and actual `down_revision` creates confusion and erodes trust in migration documentation. - **Likelihood**: Medium — most developers rely on `alembic history` for chain tracing, but some tooling (custom scripts, grep-based audits, changelogs) parses the docstring `Revises:` field. - **Priority**: Medium ### Location - **File 1**: `alembic/versions/c1_001_tool_registry_tables.py` — Lines 1–17 - **File 2**: `alembic/versions/c4_001_safety_profile_column.py` — Lines 1–17 ### Description Both migration files have a `Revises:` entry in their module docstring that does **not match** the actual `down_revision` variable — the canonical field that Alembic uses to determine migration order. #### `c1_001_tool_registry_tables.py` ```python """Add tool registry tables (tools, tool_resource_bindings, validation_attachments). ... Revision ID: c1_001_tool_registry Revises: b1_001_resource_registry # ← DOCSTRING SAYS THIS Create Date: 2026-02-14 12:00:00 """ ... revision: str = "c1_001_tool_registry" down_revision: str | Sequence[str] | None = "b0_001_projects" # ← ACTUAL PARENT ``` The docstring claims the parent is `b1_001_resource_registry`, but the actual parent is `b0_001_projects`. Alembic uses `down_revision` (the code variable), not the docstring comment. So the migration runs correctly, but the comment is wrong. #### `c4_001_safety_profile_column.py` ```python """Add safety_profile_json column to actions table. ... Revision ID: c4_001_safety_profile_column Revises: 71cd40eb661f # ← DOCSTRING SAYS THIS Create Date: 2026-02-26 00:00:00 """ ... revision: str = "c4_001_safety_profile_column" down_revision: str | Sequence[str] | None = "c0_002_merge_skill_registry" # ← ACTUAL PARENT ``` The docstring claims the parent is `71cd40eb661f` (the old merge-resource-links migration), but the actual parent is `c0_002_merge_skill_registry`. Both are likely a result of the `Revises:` line being written with an earlier draft value and not updated after the migration was rebased or repointed. ### Evidence ```bash $ grep "Revises:\|down_revision" alembic/versions/c1_001_tool_registry_tables.py Revises: b1_001_resource_registry down_revision: str | Sequence[str] | None = "b0_001_projects" $ grep "Revises:\|down_revision" alembic/versions/c4_001_safety_profile_column.py Revises: 71cd40eb661f down_revision: str | Sequence[str] | None = "c0_002_merge_skill_registry" ``` ### Expected Behavior The `Revises:` docstring field should match the `down_revision` variable exactly. By convention, Alembic-generated migrations always keep these in sync. ### Actual Behavior `Revises:` in the docstring refers to stale/incorrect parent revision IDs that no longer reflect the actual `down_revision`. ### Suggested Fix **`c1_001_tool_registry_tables.py`** — change: ```python Revises: b1_001_resource_registry ``` to: ```python Revises: b0_001_projects ``` **`c4_001_safety_profile_column.py`** — change: ```python Revises: 71cd40eb661f ``` to: ```python Revises: c0_002_merge_skill_registry ``` Consider adding a CI check (e.g., a custom `alembic check` script or pre-commit hook) that validates the docstring `Revises:` field matches `down_revision` for all migrations. ### 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:56 +00:00

HAL9000 added this to the v3.2.0 milestone

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

HAL9000 referenced this issue