Beads Migration and Schema Check

Read-only detection of whether a repository needs classic-to-Dolt migration, a Dolt schema upgrade, or no action. Reports the current state without changing files, databases, remotes, or Git state.

When to Use

• Before running /beads-migrate-to-dolt
• After upgrading bd, especially across a minor or major version
• When bd reports pending schema migrations or a remote migration gate
• When bd commands fail and the storage format or schema may be stale
• When onboarding to a repo with beads

Instructions

1. Check for Beads Installation

ls -la .beads/ 2>/dev/null

If no .beads/ directory exists, report "No beads installation found" and stop.

2. Detect Storage Format

On-disk inspection is authoritative:

# Classic format indicators
test -f .beads/beads.db && echo "FOUND: SQLite database"
test -f .beads/issues.jsonl && echo "FOUND: JSONL issues file"

# Dolt format indicators
test -d .beads/dolt && echo "FOUND: server-mode Dolt directory"
test -d .beads/embeddeddolt && echo "FOUND: legacy embedded-Dolt directory"
test -f .beads/metadata.json && cat .beads/metadata.json

issues.jsonl is not proof of classic storage: modern bd can export JSONL for interchange while Dolt remains authoritative.

3. Check Configuration, Remotes, and Worktrees

Safety gate before store-opening probes: bd may auto-migrate on store open. On an old, unknown or potentially pending schema, stop at file-only evidence unless the installed probe path is proven nonmutating. Recommend the migration core's protected-backup path for separate authorization; do not perform its backup or migration from this read-only check. The bd commands below are conditional on that proof, not permission to open an unprotected store.

cat .beads/config.yaml 2>/dev/null
git worktree list 2>/dev/null

For a Dolt repository also run:

bd dolt status 2>&1 || true
bd dolt remote list 2>&1 || true
bd config get no-push 2>&1 || true

Look for:

• sync.remote or sync.branch in config
• A configured Dolt remote
• Worktrees at .git/beads-worktrees/ from the classic sync mechanism

4. Check bd and Schema Compatibility

bd --version 2>/dev/null
bd migrate --inspect --json 2>&1 || true

Treat the inspection output as diagnostic even when it exits non-zero. On bd 1.1+, a remote-backed database with pending migrations intentionally refuses automatic migration and returns a remote_migrate_gate. Do not bypass that gate during this read-only check.

For classic data, optionally collect the legacy diagnostic too:

bd doctor --migration=pre 2>&1 || true

Do not trust bd doctor to classify storage: newer versions may inspect configured defaults rather than the files on disk, and embedded mode may not support it.

5. Classify and Report

Include in the report:

• Current storage format and mode
• bd CLI version
• Current and target schema versions, when available
• Issue count, when readable
• Configured Dolt remote or sync branch
• Whether no-push is enabled and will require a one-command approved override
• Whether classic worktrees exist
• Any remote_migrate_gate and its two choices
• Clear recommendation: migrate classic data, upgrade schema here, adopt another clone, repair, or do nothing

Remote-Backed Upgrade Safety

When bd 1.1+ reports pending schema migrations on a database with a remote:

• Never set BD_ALLOW_REMOTE_MIGRATE=1 during this check.
• Ask the operator which single clone is the designated migrator.
• The designated clone backs up, runs BD_ALLOW_REMOTE_MIGRATE=1 bd migrate, verifies, then pushes.
• Ask for explicit permission immediately before bd dolt push.
• Other clones preserve any unpushed issues, then use bd bootstrap to adopt the published schema. They must not migrate independently because that forks schema history.

Rules

• This skill is strictly read-only. Never modify files, databases, remotes, or Git state.
• Always preserve output from commands that may fail on old formats or a migration gate.
• Prefer on-disk evidence over backend defaults reported by old bd doctor versions.
• Never recommend independent schema migration on multiple clones of one Dolt remote.