beads-check-dolt-migration · diff
v1.0.0 to v1.1.0
66 added, 34 removed. Audit A to A.
---
name: beads-check-dolt-migration
- description: "Detect whether a beads installation needs migration from classic format (SQLite/JSONL) to Dolt."
+ description: "Detect whether a beads repository needs classic-to-Dolt migration or an in-place Dolt schema upgrade."
allowed-tools: "Read,Bash(bd:*),Bash(git:*),Bash(ls:*),Bash(test:*),Bash(cat:*)"
model-tier: economy
model: haiku
effort: medium
- version: "1.0.0"
+ version: "1.1.0"
author: "flurdy"
---
- # Beads Migration Check
+ # Beads Migration and Schema Check
- Read-only detection of whether a repository's beads installation needs migration to Dolt. Reports the current state and recommends next steps without making any changes.
+ 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` to understand what's needed
- - When `bd` commands fail and you suspect a format mismatch
- - As a diagnostic when onboarding to a repo with beads
-
- ## Usage
-
- ```
- /beads-check-migration
- ```
+ - 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
```bash
ls -la .beads/ 2>/dev/null
```
If no `.beads/` directory exists, report "No beads installation found" and stop.
### 2. Detect Storage Format
- Check for indicators of each format:
+ On-disk inspection is authoritative:
```bash
# 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: Dolt database directory"
+ 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
```
- ### 3. Check Sync Branch and Worktrees
+ `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
+
```bash
cat .beads/config.yaml 2>/dev/null
git worktree list 2>/dev/null
```
+ For a Dolt repository also run:
+
+ ```bash
+ bd dolt status 2>&1 || true
+ bd dolt remote list 2>&1 || true
+ bd config get no-push 2>&1 || true
+ ```
+
Look for:
- - `sync-branch` setting in config.yaml
- - Worktrees at `.git/beads-worktrees/` (classic sync mechanism)
+ - `sync.remote` or `sync.branch` in config
+ - A configured Dolt remote
+ - Worktrees at `.git/beads-worktrees/` from the classic sync mechanism
- ### 4. Check bd CLI Compatibility
+ ### 4. Check bd and Schema Compatibility
```bash
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:
+
+ ```bash
bd doctor --migration=pre 2>&1 || true
```
- ### 5. Classify and Report
+ 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.
- Based on findings, classify the state and report:
+ ### 5. Classify and Report
| State | Indicators | Recommendation |
- |-------|-----------|----------------|
- | **Classic** | `beads.db` exists, no `dolt/` | Migration needed — run `/beads-migrate-to-dolt` |
- | **JSONL-only** | `issues.jsonl` exists, no `beads.db`, no `dolt/` | Migration needed — run `/beads-migrate-to-dolt` |
- | **Already Dolt** | `dolt/` exists, metadata says `"backend": "dolt"` | No migration needed |
- | **Partial** | `dolt/` exists but empty/broken, classic files remain | Migration incomplete — run `/beads-migrate-to-dolt` to resume |
- | **No beads** | No `.beads/` directory | Not a beads repo — run `bd init` for fresh installation |
+ |-------|------------|----------------|
+ | **Classic** | `beads.db` exists, no Dolt directory | Full migration needed |
+ | **JSONL-only** | `issues.jsonl` exists, no SQLite or Dolt directory | Initialize Dolt and import |
+ | **Dolt, current** | Dolt directory exists, `bd migrate --inspect` reports no pending migrations | No migration needed |
+ | **Dolt, pending (local-only)** | Inspection reports pending migrations and no Dolt remote | Back up, then run the schema-upgrade path |
+ | **Dolt, pending (remote-backed)** | Inspection returns `remote_migrate_gate` | Choose exactly one designated clone to migrate and push; every other clone must adopt with `bd bootstrap` |
+ | **Partial/broken Dolt** | Dolt directory exists but `bd list` or `bd dolt status` fails | Diagnose and recover from backup or bootstrap; do not destroy data automatically |
+ | **No beads** | No `.beads/` directory | Run `bd init` only if the repo should use beads |
Include in the report:
- - Current format detected
+ - Current storage format and mode
- bd CLI version
- - Whether sync branch is configured (and branch name)
+ - 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 warnings from `bd doctor --migration=pre`
- - Clear recommendation (migrate, no action needed, or init)
+ - 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, or git state.
- - Always run `bd doctor --migration=pre` output through error handling — it may fail on old formats.
- - Report findings clearly so the user can decide whether to proceed with migration.
+ - 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.