dctracker 1.0.0__py3-none-any.whl

dct/core/version.py

@@ -0,0 +1,116 @@
+"""Version bump + autodetect logic — supports X.Y and X.Y.Z formats."""
+
+import json
+import tomllib
+from pathlib import Path
+
+
+def parse_version(version: str) -> tuple[int, ...]:
+    parts = version.strip().split(".")
+    return tuple(int(p) for p in parts)
+
+
+def format_version(parts: tuple[int, ...]) -> str:
+    return ".".join(str(p) for p in parts)
+
+
+def bump(current: str, bump_type: str) -> str:
+    """Bump version string by type (patch/minor/major).
+
+    Supports both X.Y (two-part) and X.Y.Z (three-part) formats.
+    Two-part versions get a patch level on patch bump: 0.18 → 0.18.1
+    """
+    if bump_type not in ("patch", "minor", "major"):
+        raise ValueError(f"Invalid bump type: '{bump_type}'. Valid: patch, minor, major")
+
+    parts = list(parse_version(current))
+
+    if bump_type == "major":
+        return format_version((parts[0] + 1, 0, 0) if len(parts) >= 3 else (parts[0] + 1, 0))
+    elif bump_type == "minor":
+        return format_version((parts[0], parts[1] + 1, 0) if len(parts) >= 3 else (parts[0], parts[1] + 1))
+    else:  # patch
+        if len(parts) >= 3:
+            return format_version((parts[0], parts[1], parts[2] + 1))
+        else:
+            return format_version((parts[0], parts[1], 1))
+
+
+def detect_version(path: str | Path) -> tuple[str | None, str | None]:
+    """Best-effort version detection from common project files.
+
+    Tries in order and returns the first hit:
+      1. <path>/VERSION                     — raw single line, stripped
+      2. <path>/pyproject.toml              — [project].version (PEP 621)
+      3. <path>/package.json                — .version (npm/yarn)
+      4. <path>/Cargo.toml                  — [package].version (rust)
+      5. <path>/src-tauri/tauri.conf.json   — .version (Tauri v2) or
+                                              .package.version (Tauri v1)
+
+    Returns (version, source_file) or (None, None) if no pattern matches.
+    Never raises — malformed files are silently skipped so `project add`
+    proceeds even when one of these files is corrupt.
+    """
+    base = Path(path)
+    if not base.is_dir():
+        return None, None
+
+    # 1. VERSION (raw text)
+    vf = base / "VERSION"
+    if vf.is_file():
+        try:
+            v = vf.read_text(encoding="utf-8").strip()
+            if v:
+                return v, "VERSION"
+        except (OSError, UnicodeDecodeError):
+            pass
+
+    # 2. pyproject.toml ([project].version)
+    pp = base / "pyproject.toml"
+    if pp.is_file():
+        try:
+            with open(pp, "rb") as f:
+                data = tomllib.load(f)
+            v = (data.get("project") or {}).get("version")
+            if isinstance(v, str) and v:
+                return v, "pyproject.toml"
+        except (OSError, tomllib.TOMLDecodeError):
+            pass
+
+    # 3. package.json (.version)
+    pj = base / "package.json"
+    if pj.is_file():
+        try:
+            with open(pj, encoding="utf-8") as f:
+                data = json.load(f)
+            v = data.get("version")
+            if isinstance(v, str) and v:
+                return v, "package.json"
+        except (OSError, json.JSONDecodeError, UnicodeDecodeError):
+            pass
+
+    # 4. Cargo.toml ([package].version)
+    ct = base / "Cargo.toml"
+    if ct.is_file():
+        try:
+            with open(ct, "rb") as f:
+                data = tomllib.load(f)
+            v = (data.get("package") or {}).get("version")
+            if isinstance(v, str) and v:
+                return v, "Cargo.toml"
+        except (OSError, tomllib.TOMLDecodeError):
+            pass
+
+    # 5. Tauri — v2 puts version at top level, v1 under .package.version
+    tc = base / "src-tauri" / "tauri.conf.json"
+    if tc.is_file():
+        try:
+            with open(tc, encoding="utf-8") as f:
+                data = json.load(f)
+            v = data.get("version") or (data.get("package") or {}).get("version")
+            if isinstance(v, str) and v:
+                return v, "src-tauri/tauri.conf.json"
+        except (OSError, json.JSONDecodeError, UnicodeDecodeError):
+            pass
+
+    return None, None

dct/db.py

@@ -0,0 +1,558 @@
+"""SQLAlchemy Core database layer for dct.
+
+Defines all tables, engine creation, and connection helpers.
+Uses Core (not ORM) for portability between PostgreSQL and SQLite.
+"""
+
+import sqlalchemy as sa
+from sqlalchemy import event
+
+metadata = sa.MetaData()
+
+projects = sa.Table(
+    "projects",
+    metadata,
+    sa.Column("id", sa.Integer, primary_key=True, autoincrement=True),
+    sa.Column("slug", sa.String(50), nullable=False),
+    sa.Column("name", sa.String(200), nullable=False),
+    sa.Column("path", sa.String(500)),
+    sa.Column("description", sa.Text),
+    sa.Column("current_version", sa.String(50)),
+    # #222: per-project opt-in for the dct changelog hook (default TRUE; the
+    # migration backfills existing projects from their actual dct changelog
+    # history). Opt out with `dct project changelog <slug> off`.
+    sa.Column("manages_changelog", sa.Boolean, nullable=False, server_default=sa.true()),
+    # #225: changelog file location relative to the project root (default repo
+    # root). A project keeping its changelog in a subdir points it there and
+    # /release resolves {path}/{changelog_path}. Constrained to the project root
+    # by set_changelog_path (leading '/' stripped, '..' escape rejected).
+    sa.Column("changelog_path", sa.String(500), nullable=False, server_default="changelog.md"),
+    sa.Column("created_at", sa.DateTime, nullable=False, server_default=sa.text("CURRENT_TIMESTAMP")),
+    sa.Column("updated_at", sa.DateTime, nullable=False, server_default=sa.text("CURRENT_TIMESTAMP")),
+    sa.Column("deleted_at", sa.DateTime),
+)
+
+items = sa.Table(
+    "items",
+    metadata,
+    sa.Column("id", sa.Integer, primary_key=True, autoincrement=True),
+    sa.Column("project_id", sa.Integer, sa.ForeignKey("projects.id"), nullable=False),
+    sa.Column("item_type", sa.String(20), nullable=False),
+    sa.Column("title", sa.String(500), nullable=False),
+    sa.Column("description", sa.Text),
+    sa.Column("priority", sa.String(10), nullable=False, server_default="P2"),
+    sa.Column("status", sa.String(20), nullable=False, server_default="open"),
+    sa.Column("component", sa.String(100)),
+    sa.Column("source_file", sa.String(500)),
+    sa.Column("source_lines", sa.String(100)),
+    sa.Column("tags", sa.Text, server_default="[]"),
+    sa.Column("resolution", sa.Text),
+    # NB: sprint membership is NOT a column. `in_current_sprint` is derived at
+    # read time from item_sprints + the project's active sprint (single source
+    # of truth, #216). The legacy boolean column is dropped by the migration in
+    # _apply_schema_updates.
+    sa.Column("created_at", sa.DateTime, nullable=False, server_default=sa.text("CURRENT_TIMESTAMP")),
+    sa.Column("updated_at", sa.DateTime, nullable=False, server_default=sa.text("CURRENT_TIMESTAMP")),
+    sa.Column("resolved_at", sa.DateTime),
+    sa.Column("deleted_at", sa.DateTime),
+)
+
+item_notes = sa.Table(
+    "item_notes",
+    metadata,
+    sa.Column("id", sa.Integer, primary_key=True, autoincrement=True),
+    sa.Column("item_id", sa.Integer, sa.ForeignKey("items.id"), nullable=False),
+    sa.Column("note", sa.Text, nullable=False),
+    sa.Column("created_at", sa.DateTime, nullable=False, server_default=sa.text("CURRENT_TIMESTAMP")),
+    sa.Column("deleted_at", sa.DateTime),
+)
+
+item_checkpoints = sa.Table(
+    "item_checkpoints",
+    metadata,
+    sa.Column("id", sa.Integer, primary_key=True, autoincrement=True),
+    sa.Column("item_id", sa.Integer, sa.ForeignKey("items.id"), nullable=False),
+    sa.Column("text", sa.Text, nullable=False),
+    sa.Column("status", sa.String(10), nullable=False, server_default="pending"),
+    sa.Column("sort_order", sa.Integer, nullable=False, server_default="0"),
+    # `kind` classifies the checkpoint as a 'task' (default, closeable by
+    # anyone) or a 'gate' (kind != 'task'). Pending gates block resolve_item.
+    # Open string column (not ENUM) so OSS users can define custom gate
+    # kinds; core validates against a whitelist in checkpoints.py but
+    # unknown kinds are treated as gates (conservative default).
+    sa.Column("kind", sa.String(32), nullable=False, server_default="task"),
+    sa.Column("created_at", sa.DateTime, nullable=False, server_default=sa.text("CURRENT_TIMESTAMP")),
+    sa.Column("updated_at", sa.DateTime, nullable=False, server_default=sa.text("CURRENT_TIMESTAMP")),
+    sa.Column("deleted_at", sa.DateTime),
+)
+
+changelog_entries = sa.Table(
+    "changelog_entries",
+    metadata,
+    sa.Column("id", sa.Integer, primary_key=True, autoincrement=True),
+    sa.Column("project_id", sa.Integer, sa.ForeignKey("projects.id"), nullable=False),
+    sa.Column("version", sa.String(50)),
+    sa.Column("category", sa.String(20), nullable=False),
+    sa.Column("entry", sa.Text, nullable=False),
+    sa.Column("component", sa.String(100)),
+    sa.Column("source_file", sa.String(500)),
+    sa.Column("source_lines", sa.String(100)),
+    sa.Column("related_item_id", sa.Integer, sa.ForeignKey("items.id")),
+    sa.Column("created_at", sa.DateTime, nullable=False, server_default=sa.text("CURRENT_TIMESTAMP")),
+    sa.Column("updated_at", sa.DateTime, nullable=False, server_default=sa.text("CURRENT_TIMESTAMP")),
+    sa.Column("released_at", sa.DateTime),
+    sa.Column("deleted_at", sa.DateTime),
+)
+
+session_handoffs = sa.Table(
+    "session_handoffs",
+    metadata,
+    sa.Column("id", sa.Integer, primary_key=True, autoincrement=True),
+    sa.Column("project_id", sa.Integer, sa.ForeignKey("projects.id"), nullable=False),
+    sa.Column("prompt", sa.Text, nullable=False),
+    sa.Column("context_summary", sa.Text),
+    sa.Column("scope", sa.String(100)),
+    sa.Column("created_by", sa.String(200), nullable=False),
+    sa.Column("created_at", sa.DateTime, nullable=False, server_default=sa.text("CURRENT_TIMESTAMP")),
+    sa.Column("consumed_at", sa.DateTime),
+    sa.Column("consumed_by", sa.String(200)),
+    sa.Column("deleted_at", sa.DateTime),
+)
+
+# ── v0.2.0 schema: plans / sprints / decisions ────────────────────────────────
+
+sprints = sa.Table(
+    "sprints",
+    metadata,
+    sa.Column("id", sa.Integer, primary_key=True, autoincrement=True),
+    sa.Column("project_id", sa.Integer, sa.ForeignKey("projects.id"), nullable=False),
+    sa.Column("name", sa.String(200), nullable=False),
+    sa.Column("code", sa.String(50)),  # short code: "0.5", "M0", "sprint-v0.1-ship"
+    sa.Column("kind", sa.String(20), nullable=False, server_default="sprint"),  # sprint|phase|milestone|block
+    sa.Column("status", sa.String(20), nullable=False, server_default="planned"),  # planned|active|deferred|completed|abandoned
+    sa.Column("goal", sa.Text),
+    sa.Column("started_at", sa.DateTime),
+    sa.Column("ended_at", sa.DateTime),
+    sa.Column("created_at", sa.DateTime, nullable=False, server_default=sa.text("CURRENT_TIMESTAMP")),
+    sa.Column("updated_at", sa.DateTime, nullable=False, server_default=sa.text("CURRENT_TIMESTAMP")),
+    sa.Column("deleted_at", sa.DateTime),
+)
+
+plans = sa.Table(
+    "plans",
+    metadata,
+    sa.Column("id", sa.Integer, primary_key=True, autoincrement=True),
+    sa.Column("ulid", sa.String(26), nullable=False, unique=True),
+    sa.Column("project_id", sa.Integer, sa.ForeignKey("projects.id"), nullable=False),
+    sa.Column("slug", sa.String(200), nullable=False),
+    sa.Column("title", sa.String(500), nullable=False),
+    sa.Column("kind", sa.String(20), nullable=False),  # plan|spec|roadmap|adr|retro|backlog
+    sa.Column("source_file", sa.String(1000)),        # NULL for DB-only roadmap
+    sa.Column("source_hash", sa.String(64)),          # sha256 of file at last scan
+    sa.Column("status", sa.String(20), nullable=False, server_default="active"),  # draft|active|completed|archived
+    sa.Column("sprint_id", sa.Integer, sa.ForeignKey("sprints.id")),
+    sa.Column("imported_at", sa.DateTime),            # NULL = never imported (first-import gate)
+    sa.Column("created_at", sa.DateTime, nullable=False, server_default=sa.text("CURRENT_TIMESTAMP")),
+    sa.Column("updated_at", sa.DateTime, nullable=False, server_default=sa.text("CURRENT_TIMESTAMP")),
+    sa.Column("archived_at", sa.DateTime),
+    sa.Column("deleted_at", sa.DateTime),
+)
+
+plan_sections = sa.Table(
+    "plan_sections",
+    metadata,
+    sa.Column("id", sa.Integer, primary_key=True, autoincrement=True),
+    sa.Column("ulid", sa.String(26), nullable=False, unique=True),
+    sa.Column("plan_id", sa.Integer, sa.ForeignKey("plans.id"), nullable=False),
+    sa.Column("parent_section_id", sa.Integer, sa.ForeignKey("plan_sections.id")),
+    sa.Column("heading", sa.Text, nullable=False),
+    sa.Column("depth", sa.Integer, nullable=False),  # 1=H1, 2=H2, ..., 6=H6
+    sa.Column("slug", sa.String(200)),
+    sa.Column("sort_order", sa.Integer, nullable=False, server_default="0"),
+    sa.Column("section_type", sa.String(30), nullable=False, server_default="generic"),
+    sa.Column("section_type_confidence", sa.String(10), server_default="high"),  # high|low|uncertain
+    sa.Column("needs_llm_review", sa.Boolean, nullable=False, server_default=sa.false()),
+    sa.Column("status", sa.String(20), nullable=False, server_default="pending"),
+    sa.Column("source_lines", sa.String(50)),
+    sa.Column("sprint_id", sa.Integer, sa.ForeignKey("sprints.id")),
+    sa.Column("converted_to_item_id", sa.Integer, sa.ForeignKey("items.id")),
+    sa.Column("created_at", sa.DateTime, nullable=False, server_default=sa.text("CURRENT_TIMESTAMP")),
+    sa.Column("updated_at", sa.DateTime, nullable=False, server_default=sa.text("CURRENT_TIMESTAMP")),
+    sa.Column("deleted_at", sa.DateTime),
+)
+
+plan_checkpoints = sa.Table(
+    "plan_checkpoints",
+    metadata,
+    sa.Column("id", sa.Integer, primary_key=True, autoincrement=True),
+    sa.Column("ulid", sa.String(26), nullable=False, unique=True),
+    sa.Column("plan_section_id", sa.Integer, sa.ForeignKey("plan_sections.id"), nullable=False),
+    sa.Column("text", sa.Text, nullable=False),
+    sa.Column("status", sa.String(10), nullable=False, server_default="pending"),  # pending|done|rejected
+    sa.Column("sort_order", sa.Integer, nullable=False, server_default="0"),
+    sa.Column("converted_to_item_id", sa.Integer, sa.ForeignKey("items.id")),
+    sa.Column("source_lines", sa.String(50)),
+    sa.Column("created_at", sa.DateTime, nullable=False, server_default=sa.text("CURRENT_TIMESTAMP")),
+    sa.Column("updated_at", sa.DateTime, nullable=False, server_default=sa.text("CURRENT_TIMESTAMP")),
+    sa.Column("deleted_at", sa.DateTime),
+)
+
+item_sprints = sa.Table(
+    "item_sprints",
+    metadata,
+    sa.Column("item_id", sa.Integer, sa.ForeignKey("items.id"), primary_key=True),
+    sa.Column("sprint_id", sa.Integer, sa.ForeignKey("sprints.id"), primary_key=True),
+    sa.Column("assigned_at", sa.DateTime, nullable=False, server_default=sa.text("CURRENT_TIMESTAMP")),
+    sa.Column("removed_at", sa.DateTime),
+)
+
+decisions = sa.Table(
+    "decisions",
+    metadata,
+    sa.Column("id", sa.Integer, primary_key=True, autoincrement=True),
+    sa.Column("ulid", sa.String(26), nullable=False, unique=True),
+    sa.Column("project_id", sa.Integer, sa.ForeignKey("projects.id"), nullable=False),
+    sa.Column("kind", sa.String(30), nullable=False),  # adr|sprint_amendment|inline_plan|open_question
+    sa.Column("ref_code", sa.String(50)),
+    sa.Column("title", sa.String(500), nullable=False),
+    sa.Column("context", sa.Text),
+    sa.Column("decision", sa.Text),
+    sa.Column("consequences", sa.Text),
+    sa.Column("alternatives", sa.Text),
+    sa.Column("status", sa.String(20), nullable=False, server_default="proposed"),  # proposed|accepted|superseded|rejected
+    sa.Column("superseded_by", sa.Integer, sa.ForeignKey("decisions.id")),
+    sa.Column("source_file", sa.String(1000)),
+    sa.Column("source_lines", sa.String(50)),
+    sa.Column("plan_id", sa.Integer, sa.ForeignKey("plans.id")),
+    sa.Column("plan_section_id", sa.Integer, sa.ForeignKey("plan_sections.id")),
+    sa.Column("sprint_id", sa.Integer, sa.ForeignKey("sprints.id")),
+    sa.Column("created_at", sa.DateTime, nullable=False, server_default=sa.text("CURRENT_TIMESTAMP")),
+    sa.Column("updated_at", sa.DateTime, nullable=False, server_default=sa.text("CURRENT_TIMESTAMP")),
+    sa.Column("deleted_at", sa.DateTime),
+)
+
+
+sa.Index(
+    "ix_projects_slug_active",
+    projects.c.slug,
+    unique=True,
+    sqlite_where=projects.c.deleted_at.is_(None),
+    postgresql_where=projects.c.deleted_at.is_(None),
+)
+
+sa.Index("ix_items_project_status_deleted", items.c.project_id, items.c.status, items.c.deleted_at)
+# (ix_items_sprint removed with the in_current_sprint column — membership now
+#  lives in item_sprints; the current-sprint EXISTS lookup is served by the
+#  item_sprints PK on item_id + ix_sprints_project_status.)
+sa.Index("ix_changelog_project_version_deleted", changelog_entries.c.project_id, changelog_entries.c.version, changelog_entries.c.deleted_at)
+sa.Index("ix_changelog_related_item", changelog_entries.c.related_item_id)
+sa.Index("ix_item_notes_item_deleted", item_notes.c.item_id, item_notes.c.deleted_at)
+sa.Index("ix_checkpoints_item_status_deleted", item_checkpoints.c.item_id, item_checkpoints.c.status, item_checkpoints.c.deleted_at)
+# Partial index: fast lookup of pending gates per item (hot path in resolve_item).
+# Condition must match the predicate in resolve_item exactly for planner to use it.
+sa.Index(
+    "ix_checkpoints_pending_gate",
+    item_checkpoints.c.item_id,
+    sqlite_where=sa.and_(
+        item_checkpoints.c.kind != "task",
+        item_checkpoints.c.status == "pending",
+        item_checkpoints.c.deleted_at.is_(None),
+    ),
+    postgresql_where=sa.and_(
+        item_checkpoints.c.kind != "task",
+        item_checkpoints.c.status == "pending",
+        item_checkpoints.c.deleted_at.is_(None),
+    ),
+)
+sa.Index(
+    "ix_handoffs_unconsumed",
+    session_handoffs.c.project_id,
+    session_handoffs.c.created_at.desc(),
+    sqlite_where=sa.and_(session_handoffs.c.consumed_at.is_(None), session_handoffs.c.deleted_at.is_(None)),
+    postgresql_where=sa.and_(session_handoffs.c.consumed_at.is_(None), session_handoffs.c.deleted_at.is_(None)),
+)
+
+# v0.2.0 indexes
+sa.Index(
+    "ix_plans_project_slug_active",
+    plans.c.project_id, plans.c.slug,
+    unique=True,
+    sqlite_where=plans.c.deleted_at.is_(None),
+    postgresql_where=plans.c.deleted_at.is_(None),
+)
+sa.Index("ix_plan_sections_plan", plan_sections.c.plan_id, plan_sections.c.sort_order)
+sa.Index("ix_plan_sections_parent", plan_sections.c.parent_section_id)
+sa.Index(
+    "ix_plan_sections_uncertain",
+    plan_sections.c.plan_id,
+    sqlite_where=sa.and_(plan_sections.c.needs_llm_review.is_(True), plan_sections.c.deleted_at.is_(None)),
+    postgresql_where=sa.and_(plan_sections.c.needs_llm_review.is_(True), plan_sections.c.deleted_at.is_(None)),
+)
+sa.Index("ix_plan_checkpoints_section_status", plan_checkpoints.c.plan_section_id, plan_checkpoints.c.status, plan_checkpoints.c.deleted_at)
+sa.Index(
+    "ix_sprints_project_code_active",
+    sprints.c.project_id, sprints.c.code,
+    unique=True,
+    sqlite_where=sa.and_(sprints.c.code.isnot(None), sprints.c.deleted_at.is_(None)),
+    postgresql_where=sa.and_(sprints.c.code.isnot(None), sprints.c.deleted_at.is_(None)),
+)
+sa.Index("ix_sprints_project_status", sprints.c.project_id, sprints.c.status, sprints.c.deleted_at)
+sa.Index(
+    "ix_item_sprints_sprint_active",
+    item_sprints.c.sprint_id,
+    sqlite_where=item_sprints.c.removed_at.is_(None),
+    postgresql_where=item_sprints.c.removed_at.is_(None),
+)
+sa.Index(
+    "ix_decisions_project_refcode_active",
+    decisions.c.project_id, decisions.c.ref_code,
+    unique=True,
+    sqlite_where=sa.and_(decisions.c.ref_code.isnot(None), decisions.c.deleted_at.is_(None)),
+    postgresql_where=sa.and_(decisions.c.ref_code.isnot(None), decisions.c.deleted_at.is_(None)),
+)
+sa.Index("ix_decisions_project_kind_status", decisions.c.project_id, decisions.c.kind, decisions.c.status, decisions.c.deleted_at)
+
+
+def _set_sqlite_wal(dbapi_connection, _connection_record):
+    cursor = dbapi_connection.cursor()
+    cursor.execute("PRAGMA foreign_keys=ON")
+    try:
+        cursor.execute("PRAGMA journal_mode=WAL")
+    except Exception:
+        pass
+    cursor.close()
+
+
+def get_engine(database_url: str) -> sa.Engine:
+    kwargs = {}
+    if database_url.startswith("sqlite"):
+        kwargs["connect_args"] = {"check_same_thread": False}
+
+    engine = sa.create_engine(database_url, **kwargs)
+
+    if database_url.startswith("sqlite"):
+        event.listen(engine, "connect", _set_sqlite_wal)
+
+    return engine
+
+
+def create_tables(engine: sa.Engine) -> None:
+    metadata.create_all(engine)
+    _apply_schema_updates(engine)
+
+
+def _apply_schema_updates(engine: sa.Engine) -> None:
+    """Idempotent schema updates for existing DBs (lightweight migration runner).
+
+    Each schema change (column add, index add, ...) is checked and applied
+    INDEPENDENTLY. We do NOT treat a logical group (e.g. "sprint migration")
+    as atomic — a partial prior run could leave the column in place but the
+    index missing, and we must heal each piece on the next call. This mirrors
+    the invariant-per-field rule learned from the update_item resolved_at bug
+    (core/items.py TERMINAL_STATUSES).
+
+    Dialect note: PostgreSQL is strict about BOOLEAN literals — `0` (INTEGER)
+    does NOT coerce to FALSE, the ALTER fails with DatatypeMismatch; same for
+    `1` vs TRUE in index predicates. SQLite is permissive. We emit FALSE/TRUE
+    for PostgreSQL and 0/1 for SQLite. Keep this in sync with the
+    server_default on the SQLAlchemy column definition (which uses sa.false()
+    to portably emit the correct literal at CREATE TABLE time).
+    """
+    inspector = sa.inspect(engine)
+    if "items" not in inspector.get_table_names():
+        return
+
+    col_names = {c["name"] for c in inspector.get_columns("items")}
+
+    # #222: opt-in changelog enforcement. Add projects.manages_changelog and,
+    # on first add, backfill — a project KEEPS enforcement only if it already
+    # has dct changelog history; one with none opts out (so projects registered
+    # for item-tracking but keeping their own changelog aren't wrongly blocked).
+    # New rows default TRUE via the column server_default; this block is a
+    # one-shot (guarded by column absence) so re-runs never override a later
+    # explicit `dct project changelog` toggle.
+    proj_cols = {c["name"] for c in inspector.get_columns("projects")}
+    if "manages_changelog" not in proj_cols:
+        is_pg = engine.dialect.name == "postgresql"
+        true_lit, false_lit = ("TRUE", "FALSE") if is_pg else ("1", "0")
+        with engine.begin() as conn:
+            conn.execute(sa.text(
+                f"ALTER TABLE projects ADD COLUMN manages_changelog "
+                f"BOOLEAN NOT NULL DEFAULT {true_lit}"
+            ))
+            conn.execute(sa.text(
+                f"UPDATE projects SET manages_changelog = {false_lit} "
+                "WHERE deleted_at IS NULL AND id NOT IN "
+                "(SELECT DISTINCT project_id FROM changelog_entries "
+                "WHERE deleted_at IS NULL AND project_id IS NOT NULL)"
+            ))
+
+    # #225: per-project changelog location. The ADD COLUMN DEFAULT backfills
+    # existing rows to 'changelog.md' (repo root) — no conditional UPDATE needed.
+    # Guarded by column absence so re-runs never clobber an explicit value set
+    # later via `dct project changelog-path`. VARCHAR default is dialect-portable
+    # (unlike the BOOLEAN literal dance above).
+    if "changelog_path" not in proj_cols:
+        with engine.begin() as conn:
+            conn.execute(sa.text(
+                "ALTER TABLE projects ADD COLUMN changelog_path "
+                "VARCHAR(500) NOT NULL DEFAULT 'changelog.md'"
+            ))
+
+    # v0.4.0: add item_checkpoints.kind column + partial index for gate lookup.
+    # See item #33 (gate checkpoints). Pre-v0.4 checkpoints default to kind='task'
+    # via server_default — existing resolve_item behaviour preserved for rows
+    # without explicit gate assignment.
+    if "item_checkpoints" in inspector.get_table_names():
+        cp_cols = {c["name"] for c in inspector.get_columns("item_checkpoints")}
+        cp_idx = {ix["name"] for ix in inspector.get_indexes("item_checkpoints")}
+        with engine.begin() as conn:
+            if "kind" not in cp_cols:
+                conn.execute(sa.text(
+                    "ALTER TABLE item_checkpoints ADD COLUMN kind "
+                    "VARCHAR(32) NOT NULL DEFAULT 'task'"
+                ))
+            if "ix_checkpoints_pending_gate" not in cp_idx:
+                conn.execute(sa.text(
+                    "CREATE INDEX IF NOT EXISTS ix_checkpoints_pending_gate "
+                    "ON item_checkpoints(item_id) "
+                    "WHERE kind != 'task' AND status = 'pending' AND deleted_at IS NULL"
+                ))
+
+    # v0.2.0 + #216: migrate the legacy `in_current_sprint` boolean into the
+    # item_sprints model, THEN drop the column. Sprint membership now has ONE
+    # source of truth (item_sprints + the active sprint) and is derived on read.
+    # The seed reads the column via raw SQL (it is intentionally absent from the
+    # table metadata), so this whole block self-disables once the column is gone.
+    # Order matters: seed BEFORE dropping, and drop the dependent index first
+    # (SQLite refuses to drop a column an index still references).
+    tables_after = set(inspector.get_table_names())
+
+    # Legacy sprints are HISTORY, not the current sprint — keep them 'completed'.
+    # INDEPENDENT, idempotent invariant (deliberately NOT nested under the column
+    # check): on a DB where the column was dropped before this demote existed,
+    # the legacy sprint would otherwise stay 'active' and wrongly resolve as the
+    # current sprint. Heal per-piece (the rule from this runner's docstring).
+    if "sprints" in tables_after:
+        with engine.begin() as conn:
+            conn.execute(sa.text(
+                "UPDATE sprints SET status = 'completed', "
+                "ended_at = COALESCE(ended_at, CURRENT_TIMESTAMP), "
+                "updated_at = CURRENT_TIMESTAMP "
+                "WHERE code = 'legacy' AND status = 'active' AND deleted_at IS NULL"
+            ))
+
+    # v0.2.0 + #216: migrate the legacy `in_current_sprint` boolean into the
+    # item_sprints model, THEN drop the column. Sprint membership now has ONE
+    # source of truth (item_sprints + the active sprint) and is derived on read.
+    # The seed reads the column via raw SQL (intentionally absent from the table
+    # metadata), so this block self-disables once the column is gone. Order
+    # matters: seed BEFORE dropping, drop the dependent index first (SQLite).
+    if "in_current_sprint" in col_names and {"sprints", "item_sprints"}.issubset(tables_after):
+        _migrate_legacy_sprint_flag(engine)
+        with engine.begin() as conn:
+            conn.execute(sa.text("DROP INDEX IF EXISTS ix_items_sprint"))
+            conn.execute(sa.text("ALTER TABLE items DROP COLUMN in_current_sprint"))
+
+
+def _migrate_legacy_sprint_flag(engine: sa.Engine) -> None:
+    """Seed a 'legacy' sprint per project with flagged items and link them.
+
+    Idempotent — for each project with any item where `in_current_sprint=TRUE`,
+    we ensure:
+      1. A sprints row with code='legacy' exists (created if missing).
+      2. Every flagged item has an item_sprints link ROW to that sprint,
+         created once if absent. A link later soft-removed via the v0.2 API
+         (removed_at set) is left untouched — this backfill is a one-shot seed,
+         NOT an authority that overrides v0.2 sprint-membership decisions.
+    Repeat invocations make no further writes once the invariant holds — the
+    existence probe spans the FULL (item_id, sprint_id) primary key regardless
+    of removed_at, so a re-run never collides with a soft-removed row.
+
+    One-shot seed (#216): reads the legacy `in_current_sprint` column via raw
+    SQL because the column is absent from the table metadata and is DROPPED
+    right after this seed runs (see _apply_schema_updates). No-op once the
+    column is gone, so it is always safe to call. The full-PK existence probe
+    means a re-run never collides with a soft-removed link (the #215 lesson).
+    """
+    from datetime import datetime, timezone
+
+    # The column only exists in pre-#216 DBs. Self-disable cleanly otherwise.
+    if "in_current_sprint" not in {c["name"] for c in sa.inspect(engine).get_columns("items")}:
+        return
+
+    with engine.begin() as conn:
+        # Read the legacy column via literal_column (it is absent from the table
+        # metadata) while keeping updated_at a TYPED column, so the value stays a
+        # datetime and can be reused as item_sprints.assigned_at.
+        flagged_rows = conn.execute(
+            sa.select(items.c.id, items.c.project_id, items.c.updated_at).where(
+                sa.literal_column("in_current_sprint") == sa.true(),
+                items.c.deleted_at.is_(None),
+            )
+        ).fetchall()
+        if not flagged_rows:
+            return
+
+        by_project: dict[int, list[tuple[int, "datetime"]]] = {}
+        for row in flagged_rows:
+            by_project.setdefault(row.project_id, []).append((row.id, row.updated_at))
+
+        for project_id, flagged in by_project.items():
+            existing = conn.execute(
+                sa.select(sprints.c.id).where(
+                    sprints.c.project_id == project_id,
+                    sprints.c.code == "legacy",
+                    sprints.c.deleted_at.is_(None),
+                )
+            ).first()
+            if existing:
+                sprint_id = existing.id
+            else:
+                row = conn.execute(
+                    sprints.insert()
+                    .values(
+                        project_id=project_id,
+                        name="Pre-0.1 legacy sprint",
+                        code="legacy",
+                        kind="sprint",
+                        # Legacy sprint is HISTORY, not the current sprint — it is
+                        # 'completed' so it never resolves as the active/current
+                        # sprint after #216. Items keep their membership for the
+                        # record; the user sets a fresh current sprint via /handoff.
+                        status="completed",
+                        started_at=datetime.now(timezone.utc),
+                        ended_at=datetime.now(timezone.utc),
+                    )
+                    .returning(sprints.c.id)
+                ).first()
+                assert row is not None, "INSERT RETURNING must return a row"
+                sprint_id = row.id
+
+            # Probe by the FULL primary key (item_id, sprint_id) — deliberately
+            # NOT filtered by removed_at. item_sprints_pkey spans both columns
+            # irrespective of removed_at, so a soft-removed link still occupies
+            # the slot. Filtering removed_at IS NULL here (the original bug)
+            # would miss a flagged item whose link was later soft-removed via
+            # remove_item_from_sprint, then re-INSERT it -> UniqueViolation.
+            already_linked = {
+                r.item_id for r in conn.execute(
+                    sa.select(item_sprints.c.item_id).where(
+                        item_sprints.c.sprint_id == sprint_id,
+                    )
+                )
+            }
+            for item_id, updated_at in flagged:
+                if item_id in already_linked:
+                    continue
+                conn.execute(
+                    item_sprints.insert().values(
+                        item_id=item_id,
+                        sprint_id=sprint_id,
+                        assigned_at=updated_at,
+                    )
+                )
+
+
+def row_to_dict(row: sa.Row) -> dict:
+    return dict(row._mapping)